Various docblocks improvements

examples/openid.php

@@ -32,6 +32,8 @@ $AUTH_MAP = array(
 
 /**
  * Simple function to show HTML page with given content.
+ *
+ * @return void
  */
 function show_page($contents)
 {

libraries/Advisor.class.php

@@ -10,12 +10,22 @@ if (! defined('PHPMYADMIN')) {
     exit;
 }
 
+/**
+ * Advisor class
+ *
+ * @package PhpMyAdmin
+ */
 class Advisor
 {
     var $variables;
     var $parseResult;
     var $runResult;
 
+    /**
+     * Parses and executes advisor rules
+     *
+     * @return array with run and parse results
+     */
     function run()
     {
         // HowTo: A simple Advisory system in 3 easy steps.
@@ -67,6 +77,11 @@ class Advisor
             . sprintf(__('PHP threw following error: %s'), $exception->getMessage());
     }
 
+    /**
+     * Executes advisor rules
+     *
+     * @return void
+     */
     function runRules()
     {
         $this->runResult = array(
@@ -333,6 +348,8 @@ class Advisor
     /**
      * Reads the rule file into an array, throwing errors messages on syntax
      * errors.
+     *
+     * @return array with parsed data
      */
     static function parseRulesFile()
     {
@@ -418,6 +435,14 @@ class Advisor
     }
 }
 
+/**
+ * Formats interval like 10 per hour
+ *
+ * @param integer $num       number to format
+ * @param intefer $precision required precision
+ *
+ * @return formatted string
+ */
 function ADVISOR_bytime($num, $precision)
 {
     $per = '';
@@ -443,11 +468,27 @@ function ADVISOR_bytime($num, $precision)
     return "$num $per";
 }
 
-function ADVISOR_timespanFormat($val)
+/**
+ * Wrapper for PMA_Util::timespanFormat
+ *
+ * @param int $seconds the timespan
+ *
+ * @return string  the formatted value
+ */
+function ADVISOR_timespanFormat($seconds)
 {
-    return PMA_Util::timespanFormat($val);
+    return PMA_Util::timespanFormat($seconds);
 }
 
+/**
+ * Wrapper around PMA_Util::formatByteDown
+ *
+ * @param double $value the value to format
+ * @param int    $limes the sensitiveness
+ * @param int    $comma the number of decimals to retain
+ *
+ * @return array    the formatted value and its unit
+ */
 function ADVISOR_formatByteDown($value, $limes = 6, $comma = 0)
 {
     return PMA_Util::formatByteDown($value, $limes, $comma);

libraries/Config.class.php

@@ -511,6 +511,11 @@ class PMA_Config
 
     /**
      * Checks if given URL is 200 or 404, optionally returns data
+     *
+     * @param mixed   $link     curl link
+     * @param boolean $get_body whether to retrieve body of document
+     *
+     * @return test result or data
      */
     function checkHTTP($link, $get_body = false)
     {

libraries/OutputBuffering.class.php

@@ -1,7 +1,7 @@
 <?php
 /* vim: set expandtab sw=4 ts=4 sts=4: */
 /**
- *
+ * Output buffering wrapper
  *
  * @package PhpMyAdmin
  */
@@ -10,7 +10,7 @@ if (! defined('PHPMYADMIN')) {
 }
 
 /**
- *
+ * Output buffering wrapper class
  *
  * @package PhpMyAdmin
  */
@@ -21,6 +21,11 @@ class PMA_OutputBuffering
     private $_content;
     private $_on;
 
+    /**
+     * Initializes class
+     *
+     * @return void
+     */
     private function __construct()
     {
         $this->_mode = $this->_getMode();
@@ -77,6 +82,7 @@ class PMA_OutputBuffering
      * output buffering is turned on.  It also needs to be passed $mode from
      * the PMA_outBufferModeGet() function or it will be useless.
      *
+     * @return void
      */
     public function start()
     {
@@ -98,6 +104,7 @@ class PMA_OutputBuffering
      * buffering is turned on.  It also needs to be passed $mode from the
      * PMA_outBufferModeGet() function or it will be useless.
      *
+     * @return void
      */
     public static function stop()
     {
@@ -110,11 +117,21 @@ class PMA_OutputBuffering
         PMA_Response::response();
     }
 
+    /**
+     * Gets buffer content
+     *
+     * @return buffer content
+     */
     public function getContents()
     {
         return $this->_content;
     }
 
+    /**
+     * Flushes output buffer
+     *
+     * @return void
+     */
     public function flush()
     {
         if (ob_get_status() && $this->_mode) {

libraries/PDF.class.php

@@ -26,6 +26,11 @@ class PMA_PDF extends TCPDF
     var $footerset;
     var $Alias = array();
 
+    /**
+     * Constructs PDF and configures standard parameters.
+     *
+     * @return void
+     */
     public function __construct($orientation = 'P', $unit = 'mm', $format = 'A4',
         $unicode = true, $encoding = 'UTF-8', $diskcache = false
     ) {
@@ -40,6 +45,8 @@ class PMA_PDF extends TCPDF
 
     /**
      * This function must be named "Footer" to work with the TCPDF library
+     *
+     * @return void
      */
     function Footer()
     {

libraries/logging.lib.php

@@ -13,6 +13,11 @@ if (! defined('PHPMYADMIN')) {
 
 /**
  * Logs user information to webserver logs.
+ *
+ * @param string $user   user name
+ * @param string $status status message
+ *
+ * @return void
  */
 function PMA_log_user($user, $status = 'ok')
 {

libraries/relation_cleanup.lib.php

@@ -10,11 +10,13 @@ if (! defined('PHPMYADMIN')) {
 }
 
 /**
- * Cleanu column related relation stuff
+ * Cleanup column related relation stuff
  *
- * @param string $db
- * @param string $table
- * @param string $column
+ * @param string $db     database name
+ * @param string $table  table name
+ * @param string $column column name
+ *
+ * @return void
  */
 function PMA_relationsCleanupColumn($db, $table, $column)
 {
@@ -54,8 +56,10 @@ function PMA_relationsCleanupColumn($db, $table, $column)
 /**
  * Cleanup table related relation stuff
  *
- * @param string $db
- * @param string $table
+ * @param string $db    database name
+ * @param string $table table name
+ *
+ * @return void
  */
 function PMA_relationsCleanupTable($db, $table)
 {
@@ -105,7 +109,9 @@ function PMA_relationsCleanupTable($db, $table)
 /**
  * Cleanup database related relation stuff
  *
- * @param string $db
+ * @param string $db database name
+ *
+ * @return void
  */
 function PMA_relationsCleanupDatabase($db)
 {

libraries/replication.inc.php

@@ -1,6 +1,7 @@
 <?php
 /* vim: set expandtab sw=4 ts=4 sts=4: */
 /**
+ * Replication helpers
  *
  * @package PhpMyAdmin
  */
@@ -136,8 +137,9 @@ foreach ($replication_types as $type) {
     }
 }
 
-
 /**
+ * Extracts database or table name from string
+ *
  * @param string $string contains "dbname.tablename"
  * @param string $what   what to extract (db|table)
  *
@@ -152,7 +154,10 @@ function PMA_extract_db_or_table($string, $what = 'db')
         return $list[1];
     }
 }
+
 /**
+ * Configures replication slave
+ *
  * @param string $action  possible values: START or STOP
  * @param string $control default: null, possible values: SQL_THREAD or IO_THREAD or null.
  *                        If it is set to null, it controls both SQL_THREAD and IO_THREAD
@@ -174,7 +179,10 @@ function PMA_replication_slave_control($action, $control = null, $link = null)
 
     return PMA_DBI_try_query($action . " SLAVE " . $control . ";", $link);
 }
+
 /**
+ * Changes master for replication slave
+ *
  * @param string $user     replication user on master
  * @param string $password password for the user
  * @param string $host     master's hostname or IP
@@ -234,6 +242,8 @@ function PMA_replication_connect_to_master($user, $password, $host = null, $port
     return PMA_DBI_connect($user, $password, false, $server, true);
 }
 /**
+ * Fetches position and file of current binary log on master
+ *
  * @param mixed $link mysql link
  *
  * @return array an array containing File and Position in MySQL replication
@@ -305,6 +315,8 @@ function PMA_replication_master_replicated_dbs($link = null)
  *                         note: if the server is current PMA server, use null
  * @param bool   $data     if true, then data will be copied as well
  *
+ * @return void
+ *
  * @todo improve code sharing between the function and synchronization
  */
 

libraries/replication_gui.lib.php

@@ -41,6 +41,8 @@ function PMA_replication_db_multibox()
  * prints out code for changing master
  *
  * @param String $submitname - submit button name
+ *
+ * @return void
  */
 
 function PMA_replication_gui_changemaster($submitname)
@@ -84,6 +86,8 @@ function PMA_replication_gui_changemaster($submitname)
  * @param string  $type   either master or slave
  * @param boolean $hidden if true, then default style is set to hidden, default value false
  * @param boolen  $title  if true, then title is displayed, default true
+ *
+ * @return void
  */
 function PMA_replication_print_status_table($type, $hidden = false, $title = true)
 {
@@ -172,6 +176,8 @@ function PMA_replication_print_status_table($type, $hidden = false, $title = tru
  * Prints table with slave users connected to this master
  *
  * @param boolean $hidden - if true, then default style is set to hidden, default value false
+ *
+ * @return void
  */
 function PMA_replication_print_slaves_table($hidden = false)
 {
@@ -239,6 +245,8 @@ function PMA_replication_get_username_hostname_length()
 
 /**
  * Print code to add a replication slave user to the master
+ *
+ * @return void
  */
 function PMA_replication_gui_master_addslaveuser()
 {

libraries/user_preferences.lib.php

@@ -228,6 +228,8 @@ function PMA_persist_option($path, $value, $default_value)
  * @param string $file_name
  * @param array  $params
  * @param string $hash
+ *
+ * @return void
  */
 function PMA_userprefs_redirect(array $forms, array $old_settings, $file_name,
     $params = null, $hash = null

setup/lib/form_processing.lib.php

@@ -10,6 +10,8 @@
  * Processes forms registered in $form_display, handles error correction
  *
  * @param FormDisplay $form_display
+ *
+ * @return void
  */
 function process_formset(FormDisplay $form_display)
 {

setup/lib/index.lib.php

@@ -261,6 +261,8 @@ function version_to_int($version)
  * @param bool &$is_readable
  * @param bool &$is_writable
  * @param bool &$file_exists
+ *
+ * @return void
  */
 function check_config_rw(&$is_readable, &$is_writable, &$file_exists)
 {
@@ -283,6 +285,8 @@ function check_config_rw(&$is_readable, &$is_writable, &$file_exists)
  *
  * Outputs results to message list, must be called between messages_begin()
  * and messages_end()
+ *
+ * @return void
  */
 function perform_config_checks()
 {

test/libraries/PMA_js_escape_test.php

@@ -16,6 +16,8 @@ class PMA_JS_Escape_test extends PHPUnit_Framework_TestCase
 {
     /**
      * @dataProvider variables
+     *
+     * @return void
      */
     public function testFormat($key, $value, $expected)
     {