documentation and whitespace on UrlShortenerPlugin

plugins/UrlShortener/UrlShortenerPlugin.php

@@ -44,16 +44,30 @@ abstract class UrlShortenerPlugin extends Plugin
 {
     public $shortenerName;
     public $freeService = false;
-    //------------Url Shortener plugin should implement some (or all) of these methods------------\\
+
+    // Url Shortener plugins should implement some (or all)
+    // of these methods
 
     /**
-    * Short a URL
+     * Make an URL shorter.
-    * @param url
+     *
-    * @return string shortened version of the url, or null if URL shortening failed
+     * @param string $url URL to shorten
+     *
+     * @return string shortened version of the url, or null on failure
      */
+
     protected abstract function shorten($url);
 
-    //------------These methods may help you implement your plugin------------\\
+    /**
+     * Utility to get the data at an URL
+     *
+     * @param string $url URL to fetch
+     *
+     * @return string response body
+     *
+     * @todo rename to code-standard camelCase httpGet()
+     */
+
     protected function http_get($url)
     {
         $request  = HTTPClient::start();
@@ -61,6 +75,17 @@ abstract class UrlShortenerPlugin extends Plugin
         return $response->getBody();
     }
 
+    /**
+     * Utility to post a request and get a response URL
+     *
+     * @param string $url  URL to fetch
+     * @param array  $data post parameters
+     *
+     * @return string response body
+     *
+     * @todo rename to code-standard httpPost()
+     */
+
     protected function http_post($url, $data)
     {
         $request  = HTTPClient::start();
@@ -68,28 +93,63 @@ abstract class UrlShortenerPlugin extends Plugin
         return $response->getBody();
     }
 
-    //------------Below are the methods that connect StatusNet to the implementing Url Shortener plugin------------\\
+    // Hook handlers
 
-    function onInitializePlugin(){
+    /**
+     * Called when all plugins have been initialized
+     *
+     * @return boolean hook value
+     */
+
+    function onInitializePlugin()
+    {
         if (!isset($this->shortenerName)) {
             throw new Exception("must specify a shortenerName");
         }
+        return true;
     }
 
+    /**
+     * Called when a showing the URL shortener drop-down box
+     *
+     * Properties of the shortening service currently only
+     * include whether it's a free service.
+     *
+     * @param array &$shorteners array mapping shortener name to properties
+     *
+     * @return boolean hook value
+     */
+
     function onGetUrlShorteners(&$shorteners)
     {
-        $shorteners[$this->shortenerName]=array('freeService'=>$this->freeService);
+        $shorteners[$this->shortenerName] =
+          array('freeService' => $this->freeService);
+        return true;
     }
 
+    /**
+     * Called to shorten an URL
+     *
+     * @param string $url           URL to shorten
+     * @param string $shortenerName Shortening service. Don't handle if it's
+     *                              not you!
+     * @param string &$shortenedUrl URL after shortening; out param.
+     *
+     * @return boolean hook value
+     */
+
     function onStartShortenUrl($url, $shortenerName, &$shortenedUrl)
     {
-        if($shortenerName == $this->shortenerName && strlen($url) >= common_config('site', 'shorturllength')){
+        if ($shortenerName == $this->shortenerName) {
             $result = $this->shorten($url);
             if (isset($result) && $result != null && $result !== false) {
                 $shortenedUrl = $result;
-                common_log(LOG_INFO, __CLASS__ . ": $this->shortenerName shortened $url to $shortenedUrl");
+                common_log(LOG_INFO,
+                           __CLASS__ . ": $this->shortenerName ".
+                           "shortened $url to $shortenedUrl");
                 return false;
             }
         }
+        return true;
     }
 }