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

---
 inc/ZipLib.class.php                         |  72 +++++++++-
 inc/utf8.php                                 |  95 +++++++++---
 install.php                                  |  20 +++
 lib/exe/css.php                              |  30 +++-
 lib/exe/js.php                               |  16 +++
 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 +++-
 19 files changed, 625 insertions(+), 71 deletions(-)

diff --git a/inc/ZipLib.class.php b/inc/ZipLib.class.php
index cec518b05..0b7bfa05e 100644
--- a/inc/ZipLib.class.php
+++ b/inc/ZipLib.class.php
@@ -16,6 +16,10 @@ class ZipLib {
     var $old_offset = 0;
     var $dirs = Array(".");
 
+    /**
+     * @param string $zip_name filename path to file
+     * @return array|int
+     */
     function get_List($zip_name) {
         $zip = @fopen($zip_name, 'rb');
         if(!$zip) return(0);
@@ -47,6 +51,11 @@ class ZipLib {
         return $ret;
     }
 
+    /**
+     * @param array $files   array filled with array(string filename, string data)
+     * @param bool  $compact
+     * @return array
+     */
     function Add($files,$compact) {
         if(!is_array($files[0])) $files=Array($files);
 
@@ -63,6 +72,10 @@ class ZipLib {
 
     /**
      * Zips recursively the $folder directory, from the $basedir directory
+     *
+     * @param string $folder filename path to file
+     * @param string|null $basedir
+     * @param string|null $parent
      */
     function Compress($folder, $basedir=null, $parent=null) {
         $full_path = $basedir."/".$parent.$folder;
@@ -73,6 +86,7 @@ class ZipLib {
         }
         $dir = new DirectoryIterator($full_path);
         foreach($dir as $file) {
+            /** @var DirectoryIterator $file */
             if(!$file->isDot()) {
                 $filename = $file->getFilename();
                 if($file->isDir()) {
@@ -87,6 +101,8 @@ class ZipLib {
 
     /**
      * Returns the Zip file
+     *
+     * @return string
      */
     function get_file() {
         $data = implode('', $this -> datasec);
@@ -97,6 +113,9 @@ class ZipLib {
             pack('V', strlen($ctrldir)) . pack('V', strlen($data)) . "\x00\x00";
     }
 
+    /**
+     * @param string $name the name of the directory
+     */
     function add_dir($name) {
         $name = str_replace("\\", "/", $name);
         $fr = "\x50\x4b\x03\x04\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00";
@@ -120,6 +139,11 @@ class ZipLib {
 
     /**
      * Add a file named $name from a string $data
+     *
+     * @param string $data
+     * @param string $name filename
+     * @param int $compact
+     * @return bool
      */
     function add_File($data, $name, $compact = 1) {
         $name     = str_replace('\\', '/', $name);
@@ -169,6 +193,9 @@ class ZipLib {
         return true;
     }
 
+    /**
+     * @return int
+     */
     function DosTime() {
         $timearray = getdate();
         if ($timearray['year'] < 1980) {
@@ -189,6 +216,11 @@ class ZipLib {
 
     /**
      * Extract a zip file $zn to the $to directory
+     *
+     * @param string $zn filename
+     * @param string $to filename path to file
+     * @param array $index
+     * @return array|int
      */
     function Extract ( $zn, $to, $index = Array(-1) ) {
         if(!@is_dir($to)) $this->_mkdir($to);
@@ -221,6 +253,11 @@ class ZipLib {
         return $stat;
     }
 
+    /**
+     * @param resource $zip
+     * @param array $header
+     * @return array
+     */
     function ReadFileHeader($zip, $header) {
         $binary_data = fread($zip, 30);
         $data = unpack('vchk/vid/vversion/vflag/vcompression/vmtime/vmdate/Vcrc/Vcompressed_size/Vsize/vfilename_len/vextra_len', $binary_data);
@@ -257,6 +294,10 @@ class ZipLib {
         return $header;
     }
 
+    /**
+     * @param resource $zip
+     * @return array
+     */
     function ReadCentralFileHeaders($zip){
         $binary_data = fread($zip, 46);
         $header = unpack('vchkid/vid/vversion/vversion_extracted/vflag/vcompression/vmtime/vmdate/Vcrc/Vcompressed_size/Vsize/vfilename_len/vextra_len/vcomment_len/vdisk/vinternal/Vexternal/Voffset', $binary_data);
@@ -298,6 +339,11 @@ class ZipLib {
         return $header;
     }
 
+    /**
+     * @param resource $zip
+     * @param string   $zip_name filename path to file
+     * @return array
+     */
     function ReadCentralDir($zip,$zip_name) {
         $size = filesize($zip_name);
         if ($size < 277){
@@ -338,6 +384,12 @@ class ZipLib {
         return $centd;
     }
 
+    /**
+     * @param array    $header
+     * @param string   $to     filename path to file
+     * @param resource $zip
+     * @return bool|int
+     */
     function ExtractFile($header,$to,$zip) {
         $header = $this->readfileheader($zip, $header);
 
@@ -418,12 +470,19 @@ class ZipLib {
      * centralize mkdir calls and use dokuwiki io functions
      *
      * @author Christopher Smith <chris@jalakai.co.uk>
+     *
+     * @param string $d filename path to file
+     * @return bool|int|string
      */
     function _mkdir($d) {
         return io_mkdir_p($d);
     }
 
-
+    /**
+     * @param string $zn
+     * @param string $name
+     * @return null|string
+     */
     function ExtractStr($zn, $name) {
         $zip = @fopen($zn,'rb');
         if(!$zip) return(null);
@@ -448,8 +507,13 @@ class ZipLib {
         return null;
     }
 
+    /**
+     * @param array $header
+     * @param resource $zip
+     * @return null|string
+     */
     function ExtractStrFile($header,$zip) {
-        $hdr = $this->readfileheader($zip);
+        $hdr = $this->readfileheader($zip, $header);
         $binary_data = '';
         if (!($header['external']==0x41FF0010) && !($header['external']==16)) {
             if ($header['compression']==0) {
@@ -487,6 +551,10 @@ class ZipLib {
         return null;
     }
 
+    /**
+     * @param string $val
+     * @return int|string
+     */
     function _ret_bytes($val) {
         $val = trim($val);
         $last = $val{strlen($val)-1};
diff --git a/inc/utf8.php b/inc/utf8.php
index c944667f7..b3f2b5fe8 100644
--- a/inc/utf8.php
+++ b/inc/utf8.php
@@ -43,6 +43,9 @@ if(!function_exists('utf8_isASCII')){
      * Checks if a string contains 7bit ASCII only
      *
      * @author Andreas Haerter <andreas.haerter@dev.mail-node.com>
+     *
+     * @param string $str
+     * @return bool
      */
     function utf8_isASCII($str){
         return (preg_match('/(?:[^\x00-\x7F])/', $str) !== 1);
@@ -56,6 +59,9 @@ if(!function_exists('utf8_strip')){
      * Returns a pure ASCII7 string
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $str
+     * @return string
      */
     function utf8_strip($str){
         $ascii = '';
@@ -75,6 +81,9 @@ if(!function_exists('utf8_check')){
      *
      * @author <bmorel@ssi.fr>
      * @link   http://www.php.net/manual/en/function.utf8-encode.php
+     *
+     * @param string $Str
+     * @return bool
      */
     function utf8_check($Str) {
         $len = strlen($Str);
@@ -105,6 +114,7 @@ if(!function_exists('utf8_basename')){
      *
      * @see basename()
      * @link   https://bugs.php.net/bug.php?id=37738
+     *
      * @param string $path     A path
      * @param string $suffix   If the name component ends in suffix this will also be cut off
      * @return string
@@ -134,6 +144,9 @@ if(!function_exists('utf8_strlen')){
      * @author <chernyshevsky at hotmail dot com>
      * @see    strlen()
      * @see    utf8_decode()
+     *
+     * @param string $string
+     * @return int
      */
     function utf8_strlen($string){
         return strlen(utf8_decode($string));
@@ -148,10 +161,11 @@ if(!function_exists('utf8_substr')){
      *
      * @author Harry Fuecks <hfuecks@gmail.com>
      * @author Chris Smith <chris@jalakai.co.uk>
+     *
      * @param string $str
      * @param int $offset number of UTF-8 characters offset (from left)
      * @param int $length (optional) length in UTF-8 characters from offset
-     * @return mixed string or false if failure
+     * @return string
      */
     function utf8_substr($str, $offset, $length = null) {
         if(UTF8_MBSTRING){
@@ -250,6 +264,14 @@ if(!function_exists('utf8_substr_replace')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    substr_replace()
+     *
+     * @param string $string      input string
+     * @param string $replacement the replacement
+     * @param int    $start       the replacing will begin at the start'th offset into string.
+     * @param int    $length      If given and is positive, it represents the length of the portion of string which is
+     *                            to be replaced. If length is zero then this function will have the effect of inserting
+     *                            replacement into string at the given start offset.
+     * @return string
      */
     function utf8_substr_replace($string, $replacement, $start , $length=0 ){
         $ret = '';
@@ -266,6 +288,7 @@ if(!function_exists('utf8_ltrim')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    ltrim()
+     *
      * @param  string $str
      * @param  string $charlist
      * @return string
@@ -286,6 +309,7 @@ if(!function_exists('utf8_rtrim')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    rtrim()
+     *
      * @param  string $str
      * @param  string $charlist
      * @return string
@@ -306,6 +330,7 @@ if(!function_exists('utf8_trim')){
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @see    trim()
+     *
      * @param  string $str
      * @param  string $charlist
      * @return string
@@ -326,6 +351,9 @@ if(!function_exists('utf8_strtolower')){
      * @author Leo Feyer <leo@typolight.org>
      * @see    strtolower()
      * @see    utf8_strtoupper()
+     *
+     * @param string $string
+     * @return string
      */
     function utf8_strtolower($string){
         if(UTF8_MBSTRING) return mb_strtolower($string,'utf-8');
@@ -344,6 +372,9 @@ if(!function_exists('utf8_strtoupper')){
      * @author Leo Feyer <leo@typolight.org>
      * @see    strtoupper()
      * @see    utf8_strtoupper()
+     *
+     * @param string $string
+     * @return string
      */
     function utf8_strtoupper($string){
         if(UTF8_MBSTRING) return mb_strtoupper($string,'utf-8');
@@ -359,7 +390,8 @@ if(!function_exists('utf8_ucfirst')){
      * Make a string's first character uppercase
      *
      * @author Harry Fuecks
-     * @param string
+     *
+     * @param string $str
      * @return string with first character as upper case (if applicable)
      */
     function utf8_ucfirst($str){
@@ -381,9 +413,10 @@ if(!function_exists('utf8_ucwords')){
      * Uppercase the first character of each word in a string
      *
      * @author Harry Fuecks
-     * @param string
-     * @return string with first char of each word uppercase
      * @see http://www.php.net/ucwords
+     *
+     * @param string $str
+     * @return string with first char of each word uppercase
      */
     function utf8_ucwords($str) {
         // Note: [\x0c\x09\x0b\x0a\x0d\x20] matches;
@@ -399,10 +432,11 @@ if(!function_exists('utf8_ucwords')){
      * You don't need to call this yourself
      *
      * @author Harry Fuecks
-     * @param  array $matches matches corresponding to a single word
-     * @return string with first char of the word in uppercase
      * @see utf8_ucwords
      * @see utf8_strtoupper
+     *
+     * @param  array $matches matches corresponding to a single word
+     * @return string with first char of the word in uppercase
      */
     function utf8_ucwords_callback($matches) {
         $leadingws = $matches[2];
@@ -420,6 +454,10 @@ if(!function_exists('utf8_deaccent')){
      * letters. Default is to deaccent both cases ($case = 0)
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $string
+     * @param int $case
+     * @return string
      */
     function utf8_deaccent($string,$case=0){
         if($case <= 0){
@@ -439,6 +477,9 @@ if(!function_exists('utf8_romanize')){
      * Romanize a non-latin string
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $string
+     * @return string
      */
     function utf8_romanize($string){
         if(utf8_isASCII($string)) return $string; //nothing to do
@@ -456,6 +497,7 @@ if(!function_exists('utf8_stripspecials')){
      * stripped chars (they are not included in $UTF8_SPECIAL_CHARS)
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
      * @param  string $string     The UTF8 string to strip of special chars
      * @param  string $repl       Replace special with this string
      * @param  string $additional Additional chars to strip (used in regexp char class)
@@ -480,9 +522,10 @@ if(!function_exists('utf8_strpos')){
      *
      * @author Leo Feyer <leo@typolight.org>
      * @see    strpos()
-     * @param  string
-     * @param  string
-     * @param  integer
+     *
+     * @param  string  $haystack
+     * @param  string  $needle
+     * @param  integer $offset
      * @return integer
      */
     function utf8_strpos($haystack, $needle, $offset=0){
@@ -512,6 +555,9 @@ if(!function_exists('utf8_tohtml')){
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author <vpribish at shopping dot com>
      * @link   http://www.php.net/manual/en/function.utf8-decode.php
+     *
+     * @param string $str
+     * @return string
      */
     function utf8_tohtml ($str) {
         $ret = '';
@@ -542,6 +588,7 @@ if(!function_exists('utf8_unhtml')){
      * what it should be                   -> "&#38;&amp#38;"
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
+     *
      * @param  string  $str      UTF-8 encoded string
      * @param  boolean $entities Flag controlling decoding of named entities.
      * @return string  UTF-8 encoded string with numeric (and named) entities replaced.
@@ -597,10 +644,10 @@ if(!class_exists('utf8_entity_decoder')){
         }
 
         /**
-         * Wrapper aorund unicode_to_utf8()
+         * Wrapper around unicode_to_utf8()
          *
-         * @param $c string
-         * @return mixed
+         * @param string $c
+         * @return string|false
          */
         function makeutf8($c) {
             return unicode_to_utf8(array(ord($c)));
@@ -609,7 +656,7 @@ if(!class_exists('utf8_entity_decoder')){
         /**
          * Decodes any HTML entity to it's correct UTF-8 char equivalent
          *
-         * @param $ent string An entity
+         * @param string $ent An entity
          * @return string
          */
         function decode($ent) {
@@ -640,12 +687,13 @@ if(!function_exists('utf8_to_unicode')){
      *
      * @author <hsivonen@iki.fi>
      * @author Harry Fuecks <hfuecks@gmail.com>
-     * @param  string  $str UTF-8 encoded string
-     * @param  boolean $strict Check for invalid sequences?
-     * @return mixed array of unicode code points or false if UTF-8 invalid
      * @see    unicode_to_utf8
      * @link   http://hsivonen.iki.fi/php-utf8/
      * @link   http://sourceforge.net/projects/phputf8/
+     *
+     * @param  string  $str UTF-8 encoded string
+     * @param  boolean $strict Check for invalid sequences?
+     * @return mixed array of unicode code points or false if UTF-8 invalid
      */
     function utf8_to_unicode($str,$strict=false) {
         $mState = 0;     // cached expected number of octets after the current octet
@@ -815,7 +863,8 @@ if(!function_exists('unicode_to_utf8')){
      *
      * @param  array $arr of unicode code points representing a string
      * @param  boolean $strict Check for invalid sequences?
-     * @return mixed UTF-8 string or false if array contains invalid code points
+     * @return string|false UTF-8 string or false if array contains invalid code points
+     *
      * @author <hsivonen@iki.fi>
      * @author Harry Fuecks <hfuecks@gmail.com>
      * @see    utf8_to_unicode
@@ -896,6 +945,10 @@ if(!function_exists('utf8_to_utf16be')){
      * UTF-8 to UTF-16BE conversion.
      *
      * Maybe really UCS-2 without mb_string due to utf8_to_unicode limits
+     *
+     * @param string $str
+     * @param bool $bom
+     * @return string
      */
     function utf8_to_utf16be(&$str, $bom = false) {
         $out = $bom ? "\xFE\xFF" : '';
@@ -914,6 +967,9 @@ if(!function_exists('utf16be_to_utf8')){
      * UTF-8 to UTF-16BE conversion.
      *
      * Maybe really UCS-2 without mb_string due to utf8_to_unicode limits
+     *
+     * @param string $str
+     * @return false|string
      */
     function utf16be_to_utf8(&$str) {
         $uni = unpack('n*',$str);
@@ -933,6 +989,7 @@ if(!function_exists('utf8_bad_replace')){
      *
      * @author Harry Fuecks <hfuecks@gmail.com>
      * @see http://www.w3.org/International/questions/qa-forms-utf-8
+     *
      * @param string $str to search
      * @param string $replace to replace bad bytes with (defaults to '?') - use ASCII
      * @return string
@@ -967,8 +1024,8 @@ if(!function_exists('utf8_correctIdx')){
     /**
      * adjust a byte index into a utf8 string to a utf8 character boundary
      *
-     * @param $str   string   utf8 character string
-     * @param $i     int      byte index into $str
+     * @param string $str   utf8 character string
+     * @param int    $i     byte index into $str
      * @param $next  bool     direction to search for boundary,
      *                           false = up (current character)
      *                           true = down (next character)
diff --git a/install.php b/install.php
index 767dd332f..71c2457dc 100644
--- a/install.php
+++ b/install.php
@@ -160,6 +160,8 @@ header('Content-Type: text/html; charset=utf-8');
 
 /**
  * Print the input form
+ *
+ * @param array $d submitted entry 'd' of request data
  */
 function print_form($d){
     global $lang;
@@ -265,6 +267,9 @@ function print_retry() {
  * Check validity of data
  *
  * @author Andreas Gohr
+ *
+ * @param array $d
+ * @return bool ok?
  */
 function check_data(&$d){
     static $form_default = array(
@@ -334,6 +339,9 @@ function check_data(&$d){
  * Writes the data to the config files
  *
  * @author  Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param array $d
+ * @return bool
  */
 function store_data($d){
     global $LC;
@@ -438,6 +446,10 @@ EOT;
  * Write the given content to a file
  *
  * @author  Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param string $filename
+ * @param string $data
+ * @return bool
  */
 function fileWrite($filename, $data) {
     global $error;
@@ -460,6 +472,8 @@ function fileWrite($filename, $data) {
  * unmodified main config file
  *
  * @author      Chris Smith <chris@jalakai.co.uk>
+ *
+ * @return bool
  */
 function check_configs(){
     global $error;
@@ -498,6 +512,8 @@ function check_configs(){
  * Check other installation dir/file permission requirements
  *
  * @author      Chris Smith <chris@jalakai.co.uk>
+ *
+ * @return bool
  */
 function check_permissions(){
     global $error;
@@ -533,6 +549,8 @@ function check_permissions(){
  * Check the availability of functions used in DokuWiki and the PHP version
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return bool
  */
 function check_functions(){
     global $error;
@@ -626,6 +644,8 @@ function print_errors(){
  * remove magic quotes recursivly
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $array
  */
 function remove_magic_quotes(&$array) {
     foreach (array_keys($array) as $key) {
diff --git a/lib/exe/css.php b/lib/exe/css.php
index 6c1d60751..2212656d2 100644
--- a/lib/exe/css.php
+++ b/lib/exe/css.php
@@ -162,7 +162,7 @@ function css_out(){
  * most of this function is error handling to show a nice useful error when
  * LESS compilation fails
  *
- * @param $css
+ * @param string $css
  * @return string
  */
 function css_parseless($css) {
@@ -222,6 +222,10 @@ function css_parseless($css) {
  * (sans the surrounding __ and with a ini_ prefix)
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $css
+ * @param array $replacements  array(placeholder => value)
+ * @return string
  */
 function css_applystyle($css, $replacements) {
     // we convert ini replacements to LESS variable names
@@ -250,6 +254,7 @@ function css_applystyle($css, $replacements) {
  * the stylesheet modes
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $tpl the used template
  * @return array with keys 'stylesheets' and 'replacements'
  */
@@ -320,6 +325,10 @@ function css_styleini($tpl) {
  * Amend paths used in replacement relative urls, refer FS#2879
  *
  * @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param array $replacements with key-value pairs
+ * @param string $location
+ * @return array
  */
 function css_fixreplacementurls($replacements, $location) {
     foreach($replacements as $key => $value) {
@@ -403,6 +412,10 @@ function css_filetypes(){
 /**
  * Loads a given file and fixes relative URLs with the
  * given location prefix
+ *
+ * @param string $file file system path
+ * @param string $location
+ * @return string
  */
 function css_loadfile($file,$location=''){
     $css_file = new DokuCssFile($file);
@@ -501,6 +514,9 @@ class DokuCssFile {
  * Convert local image URLs to data URLs if the filesize is small
  *
  * Callback for preg_replace_callback
+ *
+ * @param array $match
+ * @return string
  */
 function css_datauri($match){
     global $conf;
@@ -528,9 +544,11 @@ function css_datauri($match){
  * Returns a list of possible Plugin Styles (no existance check here)
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $mediatype
+ * @return array
  */
 function css_pluginstyles($mediatype='screen'){
-    global $lang;
     $list = array();
     $plugins = plugin_list();
     foreach ($plugins as $p){
@@ -549,6 +567,9 @@ function css_pluginstyles($mediatype='screen'){
  * Very simple CSS optimizer
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $css
+ * @return string
  */
 function css_compress($css){
     //strip comments through a callback
@@ -585,6 +606,9 @@ function css_compress($css){
  * Keeps short comments (< 5 chars) to maintain typical browser hacks
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $matches
+ * @return string
  */
 function css_comment_cb($matches){
     if(strlen($matches[2]) > 4) return '';
@@ -596,7 +620,7 @@ function css_comment_cb($matches){
  *
  * Strips one line comments but makes sure it will not destroy url() constructs with slashes
  *
- * @param $matches
+ * @param array $matches
  * @return string
  */
 function css_onelinecomment_cb($matches) {
diff --git a/lib/exe/js.php b/lib/exe/js.php
index bec12ef7a..97f2b52c3 100644
--- a/lib/exe/js.php
+++ b/lib/exe/js.php
@@ -154,6 +154,8 @@ function js_out(){
  * Load the given file, handle include calls and print it
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file filename path to file
  */
 function js_load($file){
     if(!@file_exists($file)) return;
@@ -189,6 +191,8 @@ function js_load($file){
  * Returns a list of possible Plugin Scripts (no existance check here)
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return array
  */
 function js_pluginscripts(){
     $list = array();
@@ -206,6 +210,8 @@ function js_pluginscripts(){
  * - Nothing is returned for plugins without an entry for $lang['js']
  *
  * @author Gabriel Birke <birke@d-scribe.de>
+ *
+ * @return array
  */
 function js_pluginstrings() {
     global $conf;
@@ -231,6 +237,8 @@ function js_pluginstrings() {
  *
  * - $lang['js'] must be an array.
  * - Nothing is returned for template without an entry for $lang['js']
+ *
+ * @return array
  */
 function js_templatestrings() {
     global $conf;
@@ -252,6 +260,9 @@ function js_templatestrings() {
  * as newline
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $string
+ * @return string
  */
 function js_escape($string){
     return str_replace('\\\\n','\\n',addslashes($string));
@@ -261,6 +272,8 @@ function js_escape($string){
  * Adds the given JavaScript code to the window.onload() event
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $func
  */
 function js_runonstart($func){
     echo "jQuery(function(){ $func; });".NL;
@@ -275,6 +288,9 @@ function js_runonstart($func){
  * @author Nick Galbreath <nickg@modp.com>
  * @author Andreas Gohr <andi@splitbrain.org>
  * @link   http://code.google.com/p/jsstrip/
+ *
+ * @param string $s
+ * @return string
  */
 function js_compress($s){
     $s = ltrim($s);     // strip all initial whitespace
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