From 253d4b48ec708eb42033862dc15c8576f44a48ed Mon Sep 17 00:00:00 2001
From: Gerrit Uitslag <klapinklapin@gmail.com>
Date: Wed, 1 Oct 2014 15:32:05 +0200
Subject: more PHPDocs, unused var, small bit code reformatting

---
 lib/plugins/auth.php                         |   4 +-
 lib/plugins/authad/auth.php                  |   7 +-
 lib/plugins/authmysql/auth.php               |  12 +-
 lib/plugins/authpgsql/auth.php               |   9 +-
 lib/plugins/authplain/auth.php               |   2 +-
 lib/plugins/config/admin.php                 |  45 +++++-
 lib/plugins/config/settings/config.class.php | 208 ++++++++++++++++++++++++---
 lib/plugins/config/settings/extra.class.php  |  96 +++++++++++++
 lib/plugins/extension/helper/extension.php   |   8 +-
 lib/plugins/extension/helper/list.php        |   1 -
 lib/plugins/info/syntax.php                  |  23 ++-
 lib/plugins/popularity/helper.php            |  13 ++
 lib/plugins/syntax.php                       |   7 +-
 lib/plugins/usermanager/admin.php            |  28 +++-
 14 files changed, 416 insertions(+), 47 deletions(-)

(limited to 'lib/plugins')

diff --git a/lib/plugins/auth.php b/lib/plugins/auth.php
index 0d6ea2fa3..021bc5d4b 100644
--- a/lib/plugins/auth.php
+++ b/lib/plugins/auth.php
@@ -116,7 +116,7 @@ class DokuWiki_Auth_Plugin extends DokuWiki_Plugin {
      * @author Gabriel Birke <birke@d-scribe.de>
      * @param string $type   Modification type ('create', 'modify', 'delete')
      * @param array  $params Parameters for the createUser, modifyUser or deleteUsers method. The content of this array depends on the modification type
-     * @return mixed Result from the modification function or false if an event handler has canceled the action
+     * @return bool|null|int Result from the modification function or false if an event handler has canceled the action
      */
     public function triggerUserMod($type, $params) {
         $validTypes = array(
@@ -238,7 +238,7 @@ class DokuWiki_Auth_Plugin extends DokuWiki_Plugin {
      * @author  Andreas Gohr <andi@splitbrain.org>
      * @param   string $user the user name
      * @param   bool $requireGroups whether or not the returned data must include groups
-     * @return  array containing user data or false
+     * @return  false|array containing user data or false
      */
     public function getUserData($user, $requireGroups=true) {
         if(!$this->cando['external']) msg("no valid authorisation system in use", -1);
diff --git a/lib/plugins/authad/auth.php b/lib/plugins/authad/auth.php
index 65f0b1647..88b56046c 100644
--- a/lib/plugins/authad/auth.php
+++ b/lib/plugins/authad/auth.php
@@ -329,6 +329,7 @@ class auth_plugin_authad extends DokuWiki_Auth_Plugin {
      * Bulk retrieval of user data
      *
      * @author  Dominik Eckelmann <dokuwiki@cosmocode.de>
+     *
      * @param   int   $start     index of first user to be returned
      * @param   int   $limit     max number of users to be returned
      * @param   array $filter    array of field/pattern pairs, null for no filter
@@ -447,7 +448,7 @@ class auth_plugin_authad extends DokuWiki_Auth_Plugin {
     /**
      * Get the domain part from a user
      *
-     * @param $user
+     * @param string $user
      * @return string
      */
     public function _userDomain($user) {
@@ -458,7 +459,7 @@ class auth_plugin_authad extends DokuWiki_Auth_Plugin {
     /**
      * Get the user part from a user
      *
-     * @param $user
+     * @param string $user
      * @return string
      */
     public function _userName($user) {
@@ -544,6 +545,7 @@ class auth_plugin_authad extends DokuWiki_Auth_Plugin {
      * The patterns are set up with $this->_constructPattern()
      *
      * @author Chris Smith <chris@jalakai.co.uk>
+     *
      * @param string $user
      * @param array  $info
      * @return bool
@@ -565,6 +567,7 @@ class auth_plugin_authad extends DokuWiki_Auth_Plugin {
      * Create a pattern for $this->_filter()
      *
      * @author Chris Smith <chris@jalakai.co.uk>
+     *
      * @param array $filter
      */
     protected function _constructPattern($filter) {
diff --git a/lib/plugins/authmysql/auth.php b/lib/plugins/authmysql/auth.php
index 0605a3bf1..0d423b6c9 100644
--- a/lib/plugins/authmysql/auth.php
+++ b/lib/plugins/authmysql/auth.php
@@ -115,7 +115,8 @@ class auth_plugin_authmysql extends DokuWiki_Auth_Plugin {
      * Check if the given config strings are set
      *
      * @author  Matthias Grimm <matthiasgrimm@users.sourceforge.net>
-     * @param   array $keys
+     *
+     * @param   string[] $keys
      * @param   bool  $wop is this a check for a write operation?
      * @return  bool
      */
@@ -668,7 +669,6 @@ class auth_plugin_authmysql extends DokuWiki_Auth_Plugin {
      *
      * @param  string  $user username of the user whose data is to be removed from the cache
      *                       if null, empty the whole cache
-     * @return none
      */
     protected function _flushUserInfoCache($user=null) {
         if (is_null($user)) {
@@ -750,7 +750,7 @@ class auth_plugin_authmysql extends DokuWiki_Auth_Plugin {
      * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
      *
      * @param  string $user  user's nick to get data for
-     * @return bool|array false on error, user info on success
+     * @return false|array false on error, user info on success
      */
     protected function _retrieveUserInfo($user) {
         $sql    = str_replace('%{user}', $this->_escape($user), $this->getConf('getUserInfo'));
@@ -837,7 +837,7 @@ class auth_plugin_authmysql extends DokuWiki_Auth_Plugin {
      * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
      *
      * @param  string $group   group name which id is desired
-     * @return mixed group id
+     * @return false|string group id
      */
     protected function _getGroupID($group) {
         if($this->dbcon) {
@@ -910,7 +910,7 @@ class auth_plugin_authmysql extends DokuWiki_Auth_Plugin {
      * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
      *
      * @param string $query  SQL string that contains the query
-     * @return array with the result table
+     * @return array|false with the result table
      */
     protected function _queryDB($query) {
         if($this->getConf('debug') >= 2) {
@@ -1001,6 +1001,8 @@ class auth_plugin_authmysql extends DokuWiki_Auth_Plugin {
      * abrogated.
      *
      * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
+     *
+     * @return bool
      */
     protected function _unlockTables() {
         if($this->dbcon) {
diff --git a/lib/plugins/authpgsql/auth.php b/lib/plugins/authpgsql/auth.php
index 4f5e3346f..06590fedd 100644
--- a/lib/plugins/authpgsql/auth.php
+++ b/lib/plugins/authpgsql/auth.php
@@ -104,7 +104,7 @@ class auth_plugin_authpgsql extends auth_plugin_authmysql {
      *
      * @author  Matthias Grimm <matthiasgrimm@users.sourceforge.net>
      *
-     * @param   array $keys
+     * @param   string[] $keys
      * @param   bool  $wop
      * @return  bool
      */
@@ -340,7 +340,7 @@ class auth_plugin_authpgsql extends auth_plugin_authmysql {
      * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
      *
      * @param  string $query  SQL string that contains the query
-     * @return array the result table
+     * @return array|false the result table
      */
     protected function _queryDB($query) {
         $resultarray = array();
@@ -363,6 +363,9 @@ class auth_plugin_authpgsql extends auth_plugin_authmysql {
      * MySQL one because it does NOT return the last insertID
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $query
+     * @return bool
      */
     protected function _modifyDB($query) {
         if($this->dbcon) {
@@ -396,6 +399,8 @@ class auth_plugin_authpgsql extends auth_plugin_authmysql {
      * Commit a transaction
      *
      * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
+     *
+     * @return bool
      */
     protected function _unlockTables() {
         if($this->dbcon) {
diff --git a/lib/plugins/authplain/auth.php b/lib/plugins/authplain/auth.php
index b3ca988b9..1ea75b100 100644
--- a/lib/plugins/authplain/auth.php
+++ b/lib/plugins/authplain/auth.php
@@ -77,7 +77,7 @@ class auth_plugin_authplain extends DokuWiki_Auth_Plugin {
      * @author  Andreas Gohr <andi@splitbrain.org>
      * @param string $user
      * @param bool $requireGroups  (optional) ignored by this plugin, grps info always supplied
-     * @return array|bool
+     * @return array|false
      */
     public function getUserData($user, $requireGroups=true) {
         if($this->users === null) $this->_loadUserData();
diff --git a/lib/plugins/config/admin.php b/lib/plugins/config/admin.php
index 835d27775..9202a221b 100644
--- a/lib/plugins/config/admin.php
+++ b/lib/plugins/config/admin.php
@@ -32,6 +32,9 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
     var $_session_started = false;
     var $_localised_prompts = false;
 
+    /**
+     * @return int
+     */
     function getMenuSort() { return 100; }
 
     /**
@@ -40,14 +43,20 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
     function handle() {
         global $ID, $INPUT;
 
-        if (!$this->_restore_session()) return $this->_close_session();
-        if ($INPUT->int('save') != 1) return $this->_close_session();
-        if (!checkSecurityToken()) return $this->_close_session();
+        if(!$this->_restore_session() || $INPUT->int('save') != 1 || !checkSecurityToken()) {
+            $this->_close_session();
+            return;
+        }
 
-        if (is_null($this->_config)) { $this->_config = new configuration($this->_file); }
+        if(is_null($this->_config)) {
+            $this->_config = new configuration($this->_file);
+        }
 
         // don't go any further if the configuration is locked
-        if ($this->_config->_locked) return $this->_close_session();
+        if($this->_config->locked) {
+            $this->_close_session();
+            return;
+        }
 
         $this->_input = $INPUT->arr('config');
 
@@ -104,6 +113,7 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
         formSecurityToken();
         $this->_print_h1('dokuwiki_settings', $this->getLang('_header_dokuwiki'));
 
+        /** @var setting[] $undefined_settings */
         $undefined_settings = array();
         $in_fieldset = false;
         $first_plugin_fieldset = true;
@@ -162,7 +172,17 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
 
         // show undefined settings list
         if ($allow_debug && !empty($undefined_settings)) {
-            function _setting_natural_comparison($a, $b) { return strnatcmp($a->_key, $b->_key); }
+            /**
+             * Callback for sorting settings
+             *
+             * @param setting $a
+             * @param setting $b
+             * @return int if $a is lower/equal/higher than $b
+             */
+            function _setting_natural_comparison($a, $b) {
+                return strnatcmp($a->_key, $b->_key);
+            }
+
             usort($undefined_settings, '_setting_natural_comparison');
             $this->_print_h1('undefined_settings', $this->getLang('_header_undefined'));
             ptln('<fieldset>');
@@ -235,6 +255,9 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
       if ($this->_session_started) session_write_close();
     }
 
+    /**
+     * @param bool $prompts
+     */
     function setupLocale($prompts=false) {
 
         parent::setupLocale();
@@ -245,6 +268,9 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
 
     }
 
+    /**
+     * @return bool
+     */
     function _setup_localised_plugin_prompts() {
         global $conf;
 
@@ -299,6 +325,8 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
      * Generates a two-level table of contents for the config plugin.
      *
      * @author Ben Coburn <btcoburn@silicodon.net>
+     *
+     * @return array
      */
     function getTOC() {
         if (is_null($this->_config)) { $this->_config = new configuration($this->_file); }
@@ -328,6 +356,7 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
 
         $t[] = html_mktocitem('configuration_manager', $this->getLang('_configuration_manager'), 1);
         $t[] = html_mktocitem('dokuwiki_settings', $this->getLang('_header_dokuwiki'), 1);
+        /** @var setting $setting */
         foreach($toc['conf'] as $setting) {
             $name = $setting->prompt($this);
             $t[] = html_mktocitem($setting->_key, $name, 2);
@@ -352,6 +381,10 @@ class admin_plugin_config extends DokuWiki_Admin_Plugin {
         return $t;
     }
 
+    /**
+     * @param string $id
+     * @param string $text
+     */
     function _print_h1($id, $text) {
         ptln('<h1 id="'.$id.'">'.$text.'</h1>');
     }
diff --git a/lib/plugins/config/settings/config.class.php b/lib/plugins/config/settings/config.class.php
index 30e7a2133..cbf6ea452 100644
--- a/lib/plugins/config/settings/config.class.php
+++ b/lib/plugins/config/settings/config.class.php
@@ -10,7 +10,9 @@
 if(!defined('CM_KEYMARKER')) define('CM_KEYMARKER','____');
 
 if (!class_exists('configuration')) {
-
+    /**
+     * Class configuration
+     */
     class configuration {
 
         var $_name = 'conf';           // name of the config variable found in the files (overridden by $config['varname'])
@@ -151,6 +153,8 @@ if (!class_exists('configuration')) {
 
         /**
          * Update last modified time stamp of the config file
+         *
+         * @return bool
          */
         public function touch_settings(){
             if ($this->locked) return false;
@@ -285,6 +289,10 @@ if (!class_exists('configuration')) {
         /**
          * not used ... conf's contents are an array!
          * reduce any multidimensional settings to one dimension using CM_KEYMARKER
+         *
+         * @param $conf
+         * @param string $prefix
+         * @return array
          */
         protected function _flatten($conf,$prefix='') {
 
@@ -403,6 +411,9 @@ if (!class_exists('configuration')) {
 }
 
 if (!class_exists('setting')) {
+    /**
+     * Class setting
+     */
     class setting {
 
         var $_key = '';
@@ -452,7 +463,7 @@ if (!class_exists('setting')) {
          * - if changed value passes error check, set $this->_local to the new value
          *
          * @param  mixed   $input   the new value
-         * @return boolean          true if changed, false otherwise (incl. on error)
+         * @return boolean          true if changed, false otherwise (also on error)
          */
         public function update($input) {
             if (is_null($input)) return false;
@@ -476,10 +487,9 @@ if (!class_exists('setting')) {
          *
          * @param DokuWiki_Plugin $plugin object of config plugin
          * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
-         * @return array(string $label_html, string $input_html)
+         * @return array with content array(string $label_html, string $input_html)
          */
         public function html(&$plugin, $echo=false) {
-            $value = '';
             $disable = '';
 
             if ($this->is_protected()) {
@@ -503,6 +513,10 @@ if (!class_exists('setting')) {
 
         /**
          * Generate string to save setting value to file according to $fmt
+         *
+         * @param string $var name of variable
+         * @param string $fmt save format
+         * @return string
          */
         public function out($var, $fmt='php') {
 
@@ -603,12 +617,15 @@ if (!class_exists('setting')) {
 
 
 if (!class_exists('setting_array')) {
+    /**
+     * Class setting_array
+     */
     class setting_array extends setting {
 
         /**
          * Create an array from a string
          *
-         * @param $string
+         * @param string $string
          * @return array
          */
         protected function _from_string($string){
@@ -622,7 +639,7 @@ if (!class_exists('setting_array')) {
         /**
          * Create a string from an array
          *
-         * @param $array
+         * @param array $array
          * @return string
          */
         protected function _from_array($array){
@@ -657,13 +674,23 @@ if (!class_exists('setting_array')) {
             return true;
         }
 
+        /**
+         * Escaping
+         *
+         * @param string $string
+         * @return string
+         */
         protected function _escape($string) {
             $tr = array("\\" => '\\\\', "'" => '\\\'');
             return "'".strtr( cleanText($string), $tr)."'";
         }
 
         /**
-         * generate string to save setting value to file according to $fmt
+         * Generate string to save setting value to file according to $fmt
+         *
+         * @param string $var name of variable
+         * @param string $fmt save format
+         * @return string
          */
         function out($var, $fmt='php') {
 
@@ -680,8 +707,14 @@ if (!class_exists('setting_array')) {
             return $out;
         }
 
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo=false) {
-            $value = '';
             $disable = '';
 
             if ($this->is_protected()) {
@@ -706,9 +739,18 @@ if (!class_exists('setting_array')) {
 }
 
 if (!class_exists('setting_string')) {
+    /**
+     * Class setting_string
+     */
     class setting_string extends setting {
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo=false) {
-            $value = '';
             $disable = '';
 
             if ($this->is_protected()) {
@@ -733,10 +775,21 @@ if (!class_exists('setting_string')) {
 }
 
 if (!class_exists('setting_password')) {
+    /**
+     * Class setting_password
+     */
     class setting_password extends setting_string {
 
         var $_code = 'plain';  // mechanism to be used to obscure passwords
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             if ($this->is_protected()) return false;
             if (!$input) return false;
@@ -751,9 +804,15 @@ if (!class_exists('setting_password')) {
             return true;
         }
 
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo=false) {
 
-            $value = '';
             $disable = $this->is_protected() ? 'disabled="disabled"' : '';
 
             $key = htmlspecialchars($this->_key);
@@ -766,7 +825,9 @@ if (!class_exists('setting_password')) {
 }
 
 if (!class_exists('setting_email')) {
-
+    /**
+     * Class setting_email
+     */
     class setting_email extends setting_string {
         var $_multiple = false;
         var $_placeholders = false;
@@ -830,7 +891,17 @@ if (!class_exists('setting_email')) {
  * @deprecated 2013-02-16
  */
 if (!class_exists('setting_richemail')) {
+    /**
+     * Class setting_richemail
+     */
     class setting_richemail extends setting_email {
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             $this->_placeholders = true;
             return parent::update($input);
@@ -840,6 +911,9 @@ if (!class_exists('setting_richemail')) {
 
 
 if (!class_exists('setting_numeric')) {
+    /**
+     * Class setting_numeric
+     */
     class setting_numeric extends setting_string {
         // This allows for many PHP syntax errors...
         // var $_pattern = '/^[-+\/*0-9 ]*$/';
@@ -848,6 +922,14 @@ if (!class_exists('setting_numeric')) {
         var $_min = null;
         var $_max = null;
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             $local = $this->_local;
             $valid = parent::update($input);
@@ -864,6 +946,13 @@ if (!class_exists('setting_numeric')) {
             return $valid;
         }
 
+        /**
+         * Generate string to save setting value to file according to $fmt
+         *
+         * @param string $var name of variable
+         * @param string $fmt save format
+         * @return string
+         */
         function out($var, $fmt='php') {
 
             if ($this->is_protected()) return '';
@@ -882,6 +971,9 @@ if (!class_exists('setting_numeric')) {
 }
 
 if (!class_exists('setting_numericopt')) {
+    /**
+     * Class setting_numericopt
+     */
     class setting_numericopt extends setting_numeric {
         // just allow an empty config
         var $_pattern = '/^(|[-]?[0-9]+(?:[-+*][0-9]+)*)$/';
@@ -889,10 +981,18 @@ if (!class_exists('setting_numericopt')) {
 }
 
 if (!class_exists('setting_onoff')) {
+    /**
+     * Class setting_onoff
+     */
     class setting_onoff extends setting_numeric {
-
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo = false) {
-            $value = '';
             $disable = '';
 
             if ($this->is_protected()) {
@@ -910,6 +1010,14 @@ if (!class_exists('setting_onoff')) {
             return array($label,$input);
         }
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             if ($this->is_protected()) return false;
 
@@ -924,12 +1032,21 @@ if (!class_exists('setting_onoff')) {
 }
 
 if (!class_exists('setting_multichoice')) {
+    /**
+     * Class setting_multichoice
+     */
     class setting_multichoice extends setting_string {
         var $_choices = array();
         var $lang; //some custom language strings are stored in setting
 
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo = false) {
-            $value = '';
             $disable = '';
             $nochoice = '';
 
@@ -972,6 +1089,14 @@ if (!class_exists('setting_multichoice')) {
             return array($label,$input);
         }
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             if (is_null($input)) return false;
             if ($this->is_protected()) return false;
@@ -989,10 +1114,20 @@ if (!class_exists('setting_multichoice')) {
 
 
 if (!class_exists('setting_dirchoice')) {
+    /**
+     * Class setting_dirchoice
+     */
     class setting_dirchoice extends setting_multichoice {
 
         var $_dir = '';
 
+        /**
+         * Receives current values for the setting $key
+         *
+         * @param mixed $default   default setting value
+         * @param mixed $local     local setting value
+         * @param mixed $protected protected setting value
+         */
         function initialize($default,$local,$protected) {
 
             // populate $this->_choices with a list of directories
@@ -1018,12 +1153,18 @@ if (!class_exists('setting_dirchoice')) {
 
 
 if (!class_exists('setting_hidden')) {
+    /**
+     * Class setting_hidden
+     */
     class setting_hidden extends setting {
         // Used to explicitly ignore a setting in the configuration manager.
     }
 }
 
 if (!class_exists('setting_fieldset')) {
+    /**
+     * Class setting_fieldset
+     */
     class setting_fieldset extends setting {
         // A do-nothing class used to detect the 'fieldset' type.
         // Used to start a new settings "display-group".
@@ -1031,6 +1172,9 @@ if (!class_exists('setting_fieldset')) {
 }
 
 if (!class_exists('setting_undefined')) {
+    /**
+     * Class setting_undefined
+     */
     class setting_undefined extends setting_hidden {
         // A do-nothing class used to detect settings with no metadata entry.
         // Used internaly to hide undefined settings, and generate the undefined settings list.
@@ -1038,6 +1182,9 @@ if (!class_exists('setting_undefined')) {
 }
 
 if (!class_exists('setting_no_class')) {
+    /**
+     * Class setting_no_class
+     */
     class setting_no_class extends setting_undefined {
         // A do-nothing class used to detect settings with a missing setting class.
         // Used internaly to hide undefined settings, and generate the undefined settings list.
@@ -1045,6 +1192,9 @@ if (!class_exists('setting_no_class')) {
 }
 
 if (!class_exists('setting_no_default')) {
+    /**
+     * Class setting_no_default
+     */
     class setting_no_default extends setting_undefined {
         // A do-nothing class used to detect settings with no default value.
         // Used internaly to hide undefined settings, and generate the undefined settings list.
@@ -1052,11 +1202,22 @@ if (!class_exists('setting_no_default')) {
 }
 
 if (!class_exists('setting_multicheckbox')) {
+    /**
+     * Class setting_multicheckbox
+     */
     class setting_multicheckbox extends setting_string {
 
         var $_choices = array();
         var $_combine = array();
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             if ($this->is_protected()) return false;
 
@@ -1077,9 +1238,15 @@ if (!class_exists('setting_multicheckbox')) {
             return true;
         }
 
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo=false) {
 
-            $value = '';
             $disable = '';
 
             if ($this->is_protected()) {
@@ -1141,6 +1308,9 @@ if (!class_exists('setting_multicheckbox')) {
 
         /**
          * convert comma separated list to an array and combine any complimentary values
+         *
+         * @param string $str
+         * @return array
          */
         function _str2array($str) {
             $array = explode(',',$str);
@@ -1164,6 +1334,9 @@ if (!class_exists('setting_multicheckbox')) {
 
         /**
          * convert array of values + other back to a comma separated list, incl. splitting any combined values
+         *
+         * @param array $input
+         * @return string
          */
         function _array2str($input) {
 
@@ -1192,6 +1365,9 @@ if (!class_exists('setting_multicheckbox')) {
 }
 
 if (!class_exists('setting_regex')){
+    /**
+     * Class setting_regex
+     */
     class setting_regex extends setting_string {
 
         var $_delimiter = '/';    // regex delimiter to be used in testing input
@@ -1215,7 +1391,7 @@ if (!class_exists('setting_regex')){
             // see if the regex compiles and runs (we don't check for effectiveness)
             $regex = $this->_delimiter . $input . $this->_delimiter . $this->_pregflags;
             $lastError = error_get_last();
-            $ok = @preg_match($regex,'testdata');
+            @preg_match($regex,'testdata');
             if (preg_last_error() != PREG_NO_ERROR || error_get_last() != $lastError) {
                 $this->_input = $input;
                 $this->_error = true;
diff --git a/lib/plugins/config/settings/extra.class.php b/lib/plugins/config/settings/extra.class.php
index 02171fb77..232a8177f 100644
--- a/lib/plugins/config/settings/extra.class.php
+++ b/lib/plugins/config/settings/extra.class.php
@@ -6,8 +6,15 @@
  */
 
 if (!class_exists('setting_sepchar')) {
+    /**
+     * Class setting_sepchar
+     */
     class setting_sepchar extends setting_multichoice {
 
+        /**
+         * @param string $key
+         * @param array|null $param array with metadata of setting
+         */
         function setting_sepchar($key,$param=null) {
             $str = '_-.';
             for ($i=0;$i<strlen($str);$i++) $this->_choices[] = $str{$i};
@@ -19,8 +26,19 @@ if (!class_exists('setting_sepchar')) {
 }
 
 if (!class_exists('setting_savedir')) {
+    /**
+     * Class setting_savedir
+     */
     class setting_savedir extends setting_string {
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             if ($this->is_protected()) return false;
 
@@ -40,9 +58,20 @@ if (!class_exists('setting_savedir')) {
 }
 
 if (!class_exists('setting_authtype')) {
+    /**
+     * Class setting_authtype
+     */
     class setting_authtype extends setting_multichoice {
 
+        /**
+         * Receives current values for the setting $key
+         *
+         * @param mixed $default   default setting value
+         * @param mixed $local     local setting value
+         * @param mixed $protected protected setting value
+         */
         function initialize($default,$local,$protected) {
+            /** @var $plugin_controller Doku_Plugin_Controller */
             global $plugin_controller;
 
             // retrieve auth types provided by plugins
@@ -53,7 +82,16 @@ if (!class_exists('setting_authtype')) {
             parent::initialize($default,$local,$protected);
         }
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
+            /** @var $plugin_controller Doku_Plugin_Controller */
             global $plugin_controller;
 
             // is an update possible/requested?
@@ -92,8 +130,19 @@ if (!class_exists('setting_authtype')) {
 }
 
 if (!class_exists('setting_im_convert')) {
+    /**
+     * Class setting_im_convert
+     */
     class setting_im_convert extends setting_string {
 
+        /**
+         * update changed setting with user provided value $input
+         * - if changed value fails error check, save it to $this->_input (to allow echoing later)
+         * - if changed value passes error check, set $this->_local to the new value
+         *
+         * @param  mixed   $input   the new value
+         * @return boolean          true if changed, false otherwise (also on error)
+         */
         function update($input) {
             if ($this->is_protected()) return false;
 
@@ -115,8 +164,18 @@ if (!class_exists('setting_im_convert')) {
 }
 
 if (!class_exists('setting_disableactions')) {
+    /**
+     * Class setting_disableactions
+     */
     class setting_disableactions extends setting_multicheckbox {
 
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo=false) {
             global $lang;
 
@@ -134,10 +193,20 @@ if (!class_exists('setting_disableactions')) {
 }
 
 if (!class_exists('setting_compression')) {
+    /**
+     * Class setting_compression
+     */
     class setting_compression extends setting_multichoice {
 
         var $_choices = array('0');      // 0 = no compression, always supported
 
+        /**
+         * Receives current values for the setting $key
+         *
+         * @param mixed $default   default setting value
+         * @param mixed $local     local setting value
+         * @param mixed $protected protected setting value
+         */
         function initialize($default,$local,$protected) {
 
             // populate _choices with the compression methods supported by this php installation
@@ -150,10 +219,20 @@ if (!class_exists('setting_compression')) {
 }
 
 if (!class_exists('setting_license')) {
+    /**
+     * Class setting_license
+     */
     class setting_license extends setting_multichoice {
 
         var $_choices = array('');      // none choosen
 
+        /**
+         * Receives current values for the setting $key
+         *
+         * @param mixed $default   default setting value
+         * @param mixed $local     local setting value
+         * @param mixed $protected protected setting value
+         */
         function initialize($default,$local,$protected) {
             global $license;
 
@@ -169,10 +248,20 @@ if (!class_exists('setting_license')) {
 
 
 if (!class_exists('setting_renderer')) {
+    /**
+     * Class setting_renderer
+     */
     class setting_renderer extends setting_multichoice {
         var $_prompts = array();
         var $_format = null;
 
+        /**
+         * Receives current values for the setting $key
+         *
+         * @param mixed $default   default setting value
+         * @param mixed $local     local setting value
+         * @param mixed $protected protected setting value
+         */
         function initialize($default,$local,$protected) {
             $format = $this->_format;
 
@@ -189,6 +278,13 @@ if (!class_exists('setting_renderer')) {
             parent::initialize($default,$local,$protected);
         }
 
+        /**
+         * Build html for label and input of setting
+         *
+         * @param DokuWiki_Plugin $plugin object of config plugin
+         * @param bool            $echo   true: show inputted value, when error occurred, otherwise the stored setting
+         * @return array with content array(string $label_html, string $input_html)
+         */
         function html(&$plugin, $echo=false) {
 
             // make some language adjustments (there must be a better way)
diff --git a/lib/plugins/extension/helper/extension.php b/lib/plugins/extension/helper/extension.php
index 2aca0e218..dfa624907 100644
--- a/lib/plugins/extension/helper/extension.php
+++ b/lib/plugins/extension/helper/extension.php
@@ -799,7 +799,7 @@ class helper_plugin_extension_extension extends DokuWiki_Plugin {
      *
      * The directory is registered for cleanup when the class is destroyed
      *
-     * @return bool|string
+     * @return false|string
      */
     protected function mkTmpDir(){
         $dir = io_mktmpdir();
@@ -1079,7 +1079,7 @@ class helper_plugin_extension_extension extends DokuWiki_Plugin {
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @param string $file The file to analyze
-     * @return string|bool false if the file can't be read, otherwise an "extension"
+     * @return string|false false if the file can't be read, otherwise an "extension"
      */
     private function guess_archive($file) {
         $fh = fopen($file, 'rb');
@@ -1095,6 +1095,10 @@ class helper_plugin_extension_extension extends DokuWiki_Plugin {
 
     /**
      * Copy with recursive sub-directory support
+     *
+     * @param string $src filename path to file
+     * @param string $dst filename path to file
+     * @return bool|int|string
      */
     private function dircopy($src, $dst) {
         global $conf;
diff --git a/lib/plugins/extension/helper/list.php b/lib/plugins/extension/helper/list.php
index 9b1988d84..6fc8c63b1 100644
--- a/lib/plugins/extension/helper/list.php
+++ b/lib/plugins/extension/helper/list.php
@@ -333,7 +333,6 @@ class helper_plugin_extension_list extends DokuWiki_Plugin {
      * Shortens the URL for display
      *
      * @param string $url
-     *
      * @return string  HTML link
      */
     function shortlink($url){
diff --git a/lib/plugins/info/syntax.php b/lib/plugins/info/syntax.php
index fc0e1af9d..773256faf 100644
--- a/lib/plugins/info/syntax.php
+++ b/lib/plugins/info/syntax.php
@@ -44,9 +44,14 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
         $this->Lexer->addSpecialPattern('~~INFO:\w+~~',$mode,'plugin_info');
     }
 
-
     /**
      * Handle the match
+     *
+     * @param   string       $match   The text matched by the patterns
+     * @param   int          $state   The lexer state for the match
+     * @param   int          $pos     The character position of the matched text
+     * @param   Doku_Handler $handler The Doku_Handler object
+     * @return  array Return an array with all data you want to use in render
      */
     function handle($match, $state, $pos, Doku_Handler $handler){
         $match = substr($match,7,-2); //strip ~~INFO: from start and ~~ from end
@@ -55,6 +60,11 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
 
     /**
      * Create output
+     *
+     * @param string $format   string     output format being rendered
+     * @param Doku_Renderer    $renderer  the current renderer object
+     * @param array            $data      data created by handler()
+     * @return  boolean                 rendered correctly?
      */
     function render($format, Doku_Renderer $renderer, $data) {
         if($format == 'xhtml'){
@@ -103,6 +113,9 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
      * list all installed plugins
      *
      * uses some of the original renderer methods
+     *
+     * @param string $type
+     * @param Doku_Renderer_xhtml $renderer
      */
     function _plugins_xhtml($type, Doku_Renderer_xhtml $renderer){
         global $lang;
@@ -114,7 +127,7 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
         // remove subparts
         foreach($plugins as $p){
             if (!$po = plugin_load($type,$p)) continue;
-            list($name,$part) = explode('_',$p,2);
+            list($name,/* $part */) = explode('_',$p,2);
             $plginfo[$name] = $po->getInfo();
         }
 
@@ -141,6 +154,8 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
      * list all installed plugins
      *
      * uses some of the original renderer methods
+     *
+     * @param Doku_Renderer_xhtml $renderer
      */
     function _helpermethods_xhtml(Doku_Renderer_xhtml $renderer){
         $plugins = plugin_list('helper');
@@ -189,6 +204,8 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
 
     /**
      * lists all known syntax types and their registered modes
+     *
+     * @return string
      */
     function _syntaxtypes_xhtml(){
         global $PARSER_MODES;
@@ -211,6 +228,8 @@ class syntax_plugin_info extends DokuWiki_Syntax_Plugin {
 
     /**
      * lists all known syntax modes and their sorting value
+     *
+     * @return string
      */
     function _syntaxmodes_xhtml(){
         $modes = p_get_parsermodes();
diff --git a/lib/plugins/popularity/helper.php b/lib/plugins/popularity/helper.php
index eacde06d0..b4fb33b90 100644
--- a/lib/plugins/popularity/helper.php
+++ b/lib/plugins/popularity/helper.php
@@ -74,6 +74,7 @@ class helper_plugin_popularity extends Dokuwiki_Plugin {
 
     /**
      * Check if autosubmit is enabled
+     *
      * @return boolean TRUE if we should send data once a month, FALSE otherwise
      */
     function isAutoSubmitEnabled(){
@@ -82,6 +83,7 @@ class helper_plugin_popularity extends Dokuwiki_Plugin {
 
     /**
      * Send the data, to the submit url
+     *
      * @param string $data The popularity data
      * @return string An empty string if everything worked fine, a string describing the error otherwise
      */
@@ -97,6 +99,8 @@ class helper_plugin_popularity extends Dokuwiki_Plugin {
 
     /**
      * Compute the last time the data was sent. If it has never been sent, we return 0.
+     *
+     * @return int
      */
     function lastSentTime(){
         $manualSubmission = @filemtime($this->popularityLastSubmitFile);
@@ -107,6 +111,7 @@ class helper_plugin_popularity extends Dokuwiki_Plugin {
 
     /**
      * Gather all information
+     *
      * @return string The popularity data as a string
      */
     function gatherAsString(){
@@ -124,6 +129,7 @@ class helper_plugin_popularity extends Dokuwiki_Plugin {
 
     /**
      * Gather all information
+     *
      * @return array The popularity data as an array
      */
     function _gather(){
@@ -288,17 +294,24 @@ class helper_plugin_popularity extends Dokuwiki_Plugin {
      *
      * @author <gilthans dot NO dot SPAM at gmail dot com>
      * @link   http://de3.php.net/manual/en/ini.core.php#79564
+     *
+     * @param string $v
+     * @return int|string
      */
     function _to_byte($v){
         $l = substr($v, -1);
         $ret = substr($v, 0, -1);
         switch(strtoupper($l)){
+            /** @noinspection PhpMissingBreakStatementInspection */
             case 'P':
                 $ret *= 1024;
+            /** @noinspection PhpMissingBreakStatementInspection */
             case 'T':
                 $ret *= 1024;
+            /** @noinspection PhpMissingBreakStatementInspection */
             case 'G':
                 $ret *= 1024;
+            /** @noinspection PhpMissingBreakStatementInspection */
             case 'M':
                 $ret *= 1024;
             case 'K':
diff --git a/lib/plugins/syntax.php b/lib/plugins/syntax.php
index 4a301f927..7acf681e4 100644
--- a/lib/plugins/syntax.php
+++ b/lib/plugins/syntax.php
@@ -52,6 +52,7 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode_Plugin {
      * 'stack'  - Special case. Plugin wraps other paragraphs.
      *
      * @see Doku_Handler_Block
+     *
      * @return string
      */
     function getPType(){
@@ -94,9 +95,9 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode_Plugin {
      * The contents of the $data array depends on what the handler() function above
      * created
      *
-     * @param   $format   string        output format being rendered
-     * @param   $renderer Doku_Renderer the current renderer object
-     * @param   $data     array         data created by handler()
+     * @param string          $format   output format being rendered
+     * @param Doku_Renderer   $renderer the current renderer object
+     * @param array           $data     data created by handler()
      * @return  boolean                 rendered correctly?
      */
     function render($format, Doku_Renderer $renderer, $data) {
diff --git a/lib/plugins/usermanager/admin.php b/lib/plugins/usermanager/admin.php
index c568469a7..86562f1dd 100644
--- a/lib/plugins/usermanager/admin.php
+++ b/lib/plugins/usermanager/admin.php
@@ -58,9 +58,12 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
         }
     }
 
-     /**
-      * Return prompt for admin menu
-      */
+    /**
+     * Return prompt for admin menu
+     *
+     * @param string $language
+     * @return string
+     */
     public function getMenuText($language) {
 
         if (!is_null($this->_auth))
@@ -71,6 +74,8 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
 
     /**
      * return sort order for position in admin menu
+     *
+     * @return int
      */
     public function getMenuSort() {
         return 2;
@@ -78,6 +83,8 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
 
     /**
      * Handle user request
+     *
+     * @return bool
      */
     public function handle() {
         global $INPUT;
@@ -128,6 +135,8 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
 
     /**
      * Output appropriate html
+     *
+     * @return bool
      */
     public function html() {
         global $ID;
@@ -939,8 +948,8 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
      * Returns cleaned user data
      *
      * @param array $candidate raw values of line from input file
-     * @param $error
-     * @return array|bool cleaned data or false
+     * @param string $error
+     * @return array|false cleaned data or false
      */
     protected function _cleanImportUser($candidate, & $error){
         global $INPUT;
@@ -1023,6 +1032,9 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
 
     /**
      * wrapper for is_uploaded_file to facilitate overriding by test suite
+     *
+     * @param string $file filename
+     * @return bool
      */
     protected function _isUploadedFile($file) {
         return is_uploaded_file($file);
@@ -1033,6 +1045,9 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
      *
      * @deprecated    remove when dokuwiki php requirement increases to 5.3+
      *                also associated unit test & mock access method
+     *
+     * @param string $csv string to parse
+     * @return array
      */
     protected function _getcsv($csv) {
         return function_exists('str_getcsv') ? str_getcsv($csv) : $this->str_getcsv($csv);
@@ -1043,6 +1058,9 @@ class admin_plugin_usermanager extends DokuWiki_Admin_Plugin {
      * loosely based on www.php.net/str_getcsv#88311
      *
      * @deprecated    remove when dokuwiki php requirement increases to 5.3+
+     *
+     * @param string $str string to parse
+     * @return array
      */
     protected function str_getcsv($str) {
         $fp = fopen("php://temp/maxmemory:1048576", 'r+');    // 1MiB
-- 
cgit v1.2.3