PHPDoc updates

program/lib/Roundcube/bootstrap.php

@@ -169,6 +169,10 @@ function parse_bytes($str)
 
 /**
  * Make sure the string ends with a slash
+ *
+ * @param string $str A string
+ *
+ * @return string A string ending with a slash
  */
 function slashify($str)
 {
@@ -177,6 +181,10 @@ function slashify($str)
 
 /**
  * Remove slashes at the end of the string
+ *
+ * @param string $str A string
+ *
+ * @return string A string ending with no slash
  */
 function unslashify($str)
 {
@@ -285,6 +293,12 @@ function array_keys_recursive($array)
 
 /**
  * Remove all non-ascii and non-word chars except ., -, _
+ *
+ * @param string $str          A string
+ * @param bool   $css_id       The result may be used as CSS identifier
+ * @param string $replace_with Replacement character
+ *
+ * @return string Clean string
  */
 function asciiwords($str, $css_id = false, $replace_with = '')
 {
@@ -298,7 +312,7 @@ function asciiwords($str, $css_id = false, $replace_with = '')
  * @param string $str           String to check
  * @param bool   $control_chars Includes control characters
  *
- * @return bool
+ * @return bool True if the string contains ASCII-only, False otherwise
  */
 function is_ascii($str, $control_chars = true)
 {
@@ -368,12 +382,17 @@ function version_parse($version)
     );
 }
 
-/**
+// intl replacement functions
- * intl replacement functions
- */
 
 if (!function_exists('idn_to_utf8'))
 {
+    /**
+     * Convert domain name from IDNA ASCII to Unicode
+     *
+     * @param string $domain Domain to convert in an IDNA ASCII-compatible format.
+     *
+     * @return string|false Unicode domain, False on failure
+     */
     function idn_to_utf8($domain)
     {
         static $idn, $loaded;
@@ -388,6 +407,7 @@ if (!function_exists('idn_to_utf8'))
                 $domain = $idn->decode($domain);
             }
             catch (Exception $e) {
+                return false;
             }
         }
 
@@ -397,6 +417,13 @@ if (!function_exists('idn_to_utf8'))
 
 if (!function_exists('idn_to_ascii'))
 {
+    /**
+     * Convert domain name to IDNA ASCII-compatible form Unicode
+     *
+     * @param string $domain The domain to convert, which must be UTF-8 encoded
+     *
+     * @return string|false The domain name encoded in ASCII-compatible form, False on failure
+     */
     function idn_to_ascii($domain)
     {
         static $idn, $loaded;
@@ -411,6 +438,7 @@ if (!function_exists('idn_to_ascii'))
                 $domain = $idn->encode($domain);
             }
             catch (Exception $e) {
+                return false;
             }
         }
 
@@ -421,6 +449,10 @@ if (!function_exists('idn_to_ascii'))
 /**
  * Use PHP5 autoload for dynamic class loading
  *
+ * @param string $classname Class name
+ *
+ * @return bool True when the class file has been found
+ *
  * @todo Make Zend, PEAR etc play with this
  * @todo Make our classes conform to a more straight forward CS.
  */

program/lib/Roundcube/html.php

@@ -227,6 +227,7 @@ class html
      * Derrived method to create <iframe></iframe>
      *
      * @param mixed  $attr Hash array with tag attributes or string with frame source (src)
+     * @param string $cont Tag content
      *
      * @return string HTML code
      * @see html::tag()
@@ -935,13 +936,14 @@ class html_table extends html
         $this->content = $thead . ($this->tagname == 'table' ? self::tag('tbody', null, $tbody) : $tbody);
 
         unset($this->attrib['cols'], $this->attrib['rowsonly']);
+
         return parent::show();
     }
 
     /**
      * Count number of rows
      *
-     * @return The number of rows
+     * @return int The number of rows
      */
     public function size()
     {

program/lib/Roundcube/rcube.php

@@ -39,107 +39,59 @@ class rcube
 
     const DEBUG_LINE_LENGTH = 4096;
 
-    /**
+    /** @var rcube_config Stores instance of rcube_config */
-     * Singleton instance of rcube
-     *
-     * @var rcube
-     */
-    static protected $instance;
-
-    /**
-     * Stores instance of rcube_config.
-     *
-     * @var rcube_config
-     */
     public $config;
 
-    /**
+    /** @var rcube_db Instance of database class */
-     * Instance of database class.
-     *
-     * @var rcube_db
-     */
     public $db;
 
-    /**
+    /** @var Memcache Instance of Memcache class */
-     * Instance of Memcache class.
-     *
-     * @var Memcache
-     */
     public $memcache;
 
-    /**
+    /** @var Memcached Instance of Memcached class */
-     * Instance of Memcached class.
-     *
-     * @var Memcached
-     */
     public $memcached;
 
-    /**
+    /** @var Redis Instance of Redis class */
-     * Instance of Redis class.
-     *
-     * @var Redis
-     */
     public $redis;
 
-   /**
+    /** @var rcube_session Instance of rcube_session class */
-     * Instance of rcube_session class.
-     *
-     * @var rcube_session
-     */
     public $session;
 
-    /**
+    /** @var rcube_smtp Instance of rcube_smtp class */
-     * Instance of rcube_smtp class.
-     *
-     * @var rcube_smtp
-     */
     public $smtp;
 
-    /**
+    /** @var rcube_storage Instance of rcube_storage class */
-     * Instance of rcube_storage class.
-     *
-     * @var rcube_storage
-     */
     public $storage;
 
-    /**
+    /** @var rcube_output Instance of rcube_output class */
-     * Instance of rcube_output class.
-     *
-     * @var rcube_output
-     */
     public $output;
 
-    /**
+    /** @var rcube_plugin_api Instance of rcube_plugin_api */
-     * Instance of rcube_plugin_api.
-     *
-     * @var rcube_plugin_api
-     */
     public $plugins;
 
-    /**
+    /** @var rcube_user Instance of rcube_user class */
-     * Instance of rcube_user class.
-     *
-     * @var rcube_user
-     */
     public $user;
 
-    /**
+    /** @var int Request status */
-     * Request status
-     *
-     * @var int
-     */
     public $request_status = 0;
 
-    /* private/protected vars */
+    /** @var array Localization */
     protected $texts;
+
+    /** @var rcube_cache[] Initialized cache objects */
     protected $caches = array();
+
+    /** @var array Registered shutdown functions */
     protected $shutdown_functions = array();
 
+    /** @var rcube Singleton instance of rcube */
+    static protected $instance;
+
 
     /**
      * This implements the 'singleton' design pattern
      *
-     * @param integer $mode Options to initialize with this instance. See rcube::INIT_WITH_* constants
+     * @param int    $mode Options to initialize with this instance. See rcube::INIT_WITH_* constants
      * @param string $env  Environment name to run (e.g. live, dev, test)
      *
      * @return rcube The one and only instance
@@ -156,6 +108,8 @@ class rcube
 
     /**
      * Private constructor
+     *
+     * @param string $env Environment name to run (e.g. live, dev, test)
      */
     protected function __construct($env = '')
     {
@@ -168,6 +122,8 @@ class rcube
 
     /**
      * Initial startup function
+     *
+     * @param int $mode Options to initialize with this instance. See rcube::INIT_WITH_* constants
      */
     protected function init($mode = 0)
     {
@@ -461,6 +417,8 @@ class rcube
 
     /**
      * Callback for IMAP connection events to log session identifiers
+     *
+     * @param array $args Callback arguments
      */
     public function storage_log_session($args)
     {
@@ -647,7 +605,7 @@ class rcube
      *
      * @param string $name        Label name
      * @param string $domain      Label domain (plugin) name or '*' for all domains
-     * @param string $ref_domain Sets domain name if label is found
+     * @param string &$ref_domain Sets domain name if label is found
      *
      * @return boolean True if text exists (either in the current language or in en_US)
      */
@@ -878,7 +836,7 @@ class rcube
      *
      * @param string $clear  Clear text input
      * @param string $key    Encryption key to retrieve from the configuration, defaults to 'des_key'
-     * @param boolean $base64 Whether or not to base64_encode() the result before returning
+     * @param bool   $base64 Whether or not to base64_encode() the result before returning
      *
      * @return string Encrypted text
      */
@@ -902,7 +860,7 @@ class rcube
      *
      * @param string $cipher Encrypted text
      * @param string $key    Encryption key to retrieve from the configuration, defaults to 'des_key'
-     * @param boolean $base64 Whether or not input is base64-encoded
+     * @param boo    $base64 Whether or not input is base64-encoded
      *
      * @return string Decrypted text
      */
@@ -980,7 +938,7 @@ class rcube
      *
      * @param int $mode Request method
      *
-     * @return boolean True if request token is valid false if not
+     * @return bool True if request token is valid false if not
      */
     public function check_request($mode = rcube_utils::INPUT_POST)
     {
@@ -1129,6 +1087,10 @@ class rcube
      * Quote a given string.
      * Shortcut function for rcube_utils::rep_specialchars_output()
      *
+     * @param string $str      A string to quote
+     * @param string $mode     Replace mode for tags: show|remove|strict
+     * @param bool   $newlines Convert newlines
+     *
      * @return string HTML-quoted string
      */
     public static function Q($str, $mode = 'strict', $newlines = true)
@@ -1140,6 +1102,8 @@ class rcube
      * Quote a given string for javascript output.
      * Shortcut function for rcube_utils::rep_specialchars_output()
      *
+     * @param string $str A string to quote
+     *
      * @return string JS-quoted string
      */
     public static function JQ($str)
@@ -1151,10 +1115,10 @@ class rcube
      * Construct shell command, execute it and return output as string.
      * Keywords {keyword} are replaced with arguments
      *
-     * @param $cmd    Format string with {keywords} to be replaced
+     * @param string $cmd        Format string with {keywords} to be replaced
-     * @param $values (zero, one or more arrays can be passed)
+     * @param mixed  $values,... (zero, one or more arrays can be passed)
      *
-     * @return output of command. shell errors not detectable
+     * @return string Output of command. Shell errors not detectable
      */
     public static function exec(/* $cmd, $values1 = array(), ... */)
     {
@@ -1328,8 +1292,8 @@ class rcube
      *      - message: Error message
      *      - file:    File where error occurred
      *      - line:    Line where error occurred
-     * @param boolean $log       True to log the error
+     * @param bool $log       True to log the error
-     * @param boolean $terminate Terminate script execution
+     * @param bool $terminate Terminate script execution
      */
     public static function raise_error($arg = array(), $log = false, $terminate = false)
     {
@@ -1561,6 +1525,8 @@ class rcube
 
     /**
      * Get the per-user log directory
+     *
+     * @return string|false Per-user log directory if it exists and is writable, False otherwise
      */
     protected function get_user_log_dir()
     {
@@ -1622,17 +1588,17 @@ class rcube
     /**
      * Send the given message using the configured method.
      *
-     * @param object       $message    Reference to Mail_MIME object
+     * @param Mail_Mime    &$message    Reference to Mail_MIME object
      * @param string       $from        Sender address string
      * @param array|string $mailto      Either a comma-separated list of recipients (RFC822 compliant),
      *                                  or an array of recipients, each RFC822 valid
-     * @param array        $error      SMTP error array (reference)
+     * @param array        &$error      SMTP error array (reference)
-     * @param string       $body_file  Location of file with saved message body (reference),
+     * @param string       &$body_file  Location of file with saved message body (reference),
      *                                  used when delay_file_io is enabled
      * @param array        $options     SMTP options (e.g. DSN request)
      * @param bool         $disconnect  Close SMTP connection ASAP
      *
-     * @return boolean Send status.
+     * @return bool Send status.
      */
     public function deliver_message(&$message, $from, $mailto, &$error,
         &$body_file = null, $options = null, $disconnect = false)
@@ -1759,6 +1725,11 @@ class rcube_dummy_plugin_api
 {
     /**
      * Triggers a plugin hook.
+     *
+     * @param string $hook Hook name
+     * @param array  $args Hook arguments
+     *
+     * @return array Hook arguments
      * @see rcube_plugin_api::exec_hook()
      */
     public function exec_hook($hook, $args = array())