Many PHPDocs, some unused and dyn declared vars

many PHPDocs
some unused variables
some dynamically declared variables declared

41 files changed, 1354 insertions, 249 deletions

diff --git a/bin/gittool.php b/bin/gittool.php
index 6944dde57..7991a9997 100755
--- a/bin/gittool.php
+++ b/bin/gittool.php
@@ -101,7 +101,7 @@ class GitToolCLI extends DokuCLI {
     /**
      * Tries to install the given extensions using git clone
      *
-     * @param       $extensions
+     * @param array      $extensions
      */
     public function cmd_clone($extensions) {
         $errors    = array();
@@ -130,7 +130,7 @@ class GitToolCLI extends DokuCLI {
     /**
      * Tries to install the given extensions using git clone with fallback to install
      *
-     * @param       $extensions
+     * @param array      $extensions
      */
     public function cmd_install($extensions) {
         $errors    = array();
@@ -291,7 +291,7 @@ class GitToolCLI extends DokuCLI {
      * Returns the repository for the given extension
      *
      * @param $extension
-     * @return bool|string
+     * @return false|string
      */
     private function getSourceRepo($extension) {
         /** @var helper_plugin_extension_extension $ext */
diff --git a/bin/wantedpages.php b/bin/wantedpages.php
index 8fc4ba74f..54bfd4755 100755
--- a/bin/wantedpages.php
+++ b/bin/wantedpages.php
@@ -61,6 +61,13 @@ class WantedPagesCLI extends DokuCLI {
         }
     }
 
+    /**
+     * Determine directions of the search loop
+     *
+     * @param string $entry
+     * @param string $basepath
+     * @return int
+     */
     protected function dir_filter($entry, $basepath) {
         if($entry == '.' || $entry == '..') {
             return WantedPagesCLI::DIR_CONTINUE;
@@ -77,6 +84,13 @@ class WantedPagesCLI extends DokuCLI {
         return WantedPagesCLI::DIR_CONTINUE;
     }
 
+    /**
+     * Collects recursively the pages in a namespace
+     *
+     * @param string $dir
+     * @return array
+     * @throws DokuCLI_Exception
+     */
     protected function get_pages($dir) {
         static $trunclen = null;
         if(!$trunclen) {
@@ -108,6 +122,12 @@ class WantedPagesCLI extends DokuCLI {
         return $pages;
     }
 
+    /**
+     * Parse instructions and returns the non-existing links
+     *
+     * @param array $page array with page id and file path
+     * @return array
+     */
     function internal_links($page) {
         global $conf;
         $instructions = p_get_instructions(file_get_contents($page['file']));
diff --git a/inc/DifferenceEngine.php b/inc/DifferenceEngine.php
index 3c955cf88..210d1c0eb 100644
--- a/inc/DifferenceEngine.php
+++ b/inc/DifferenceEngine.php
@@ -14,6 +14,9 @@ class _DiffOp {
     var $orig;
     var $closing;
 
+    /**
+     * @return _DiffOp
+     */
     function reverse() {
         trigger_error("pure virtual", E_USER_ERROR);
     }
@@ -104,6 +107,21 @@ class _DiffOp_Change extends _DiffOp {
  */
 class _DiffEngine {
 
+    var $xchanged = array();
+    var $ychanged = array();
+    var $xv = array();
+    var $yv = array();
+    var $xind = array();
+    var $yind = array();
+    var $seq;
+    var $in_seq;
+    var $lcs;
+
+    /**
+     * @param array $from_lines
+     * @param array $to_lines
+     * @return _DiffOp[]
+     */
     function diff($from_lines, $to_lines) {
         $n_from = count($from_lines);
         $n_to = count($to_lines);
@@ -495,9 +513,9 @@ class Diff {
      * Constructor.
      * Computes diff between sequences of strings.
      *
-     * @param $from_lines array An array of strings.
-     *      (Typically these are lines from a file.)
-     * @param $to_lines array An array of strings.
+     * @param array $from_lines An array of strings.
+     *                          (Typically these are lines from a file.)
+     * @param array $to_lines   An array of strings.
      */
     function __construct($from_lines, $to_lines) {
         $eng = new _DiffEngine;
@@ -512,8 +530,9 @@ class Diff {
      *
      *  $diff = new Diff($lines1, $lines2);
      *  $rev = $diff->reverse();
-     * @return object A Diff object representing the inverse of the
-     *          original diff.
+     *
+     * @return Diff  A Diff object representing the inverse of the
+     *               original diff.
      */
     function reverse() {
         $rev = $this;
@@ -631,19 +650,19 @@ class MappedDiff extends Diff {
      * case-insensitve diffs, or diffs which ignore
      * changes in white-space.
      *
-     * @param $from_lines array An array of strings.
-     *  (Typically these are lines from a file.)
+     * @param string[] $from_lines         An array of strings.
+     *                                     (Typically these are lines from a file.)
      *
-     * @param $to_lines array An array of strings.
+     * @param string[] $to_lines           An array of strings.
      *
-     * @param $mapped_from_lines array This array should
-     *  have the same size number of elements as $from_lines.
-     *  The elements in $mapped_from_lines and
-     *  $mapped_to_lines are what is actually compared
-     *  when computing the diff.
+     * @param string[] $mapped_from_lines  This array should
+     *                                     have the same size number of elements as $from_lines.
+     *                                     The elements in $mapped_from_lines and
+     *                                     $mapped_to_lines are what is actually compared
+     *                                     when computing the diff.
      *
-     * @param $mapped_to_lines array This array should
-     *  have the same number of elements as $to_lines.
+     * @param string[] $mapped_to_lines    This array should
+     *                                     have the same number of elements as $to_lines.
      */
     function __construct($from_lines, $to_lines, $mapped_from_lines, $mapped_to_lines) {
 
@@ -697,12 +716,13 @@ class DiffFormatter {
     /**
      * Format a diff.
      *
-     * @param $diff object A Diff object.
+     * @param Diff $diff A Diff object.
      * @return string The formatted output.
      */
     function format($diff) {
 
         $xi = $yi = 1;
+        $x0 = $y0 = 0;
         $block = false;
         $context = array();
 
@@ -752,6 +772,13 @@ class DiffFormatter {
         return $this->_end_diff();
     }
 
+    /**
+     * @param int $xbeg
+     * @param int $xlen
+     * @param int $ybeg
+     * @param int $ylen
+     * @param array $edits
+     */
     function _block($xbeg, $xlen, $ybeg, $ylen, &$edits) {
         $this->_start_block($this->_block_header($xbeg, $xlen, $ybeg, $ylen));
         foreach ($edits as $edit) {
@@ -779,6 +806,13 @@ class DiffFormatter {
         return $val;
     }
 
+    /**
+     * @param int $xbeg
+     * @param int $xlen
+     * @param int $ybeg
+     * @param int $ylen
+     * @return string
+     */
     function _block_header($xbeg, $xlen, $ybeg, $ylen) {
         if ($xlen > 1)
             $xbeg .= "," . ($xbeg + $xlen - 1);
@@ -788,6 +822,9 @@ class DiffFormatter {
         return $xbeg . ($xlen ? ($ylen ? 'c' : 'd') : 'a') . $ybeg;
     }
 
+    /**
+     * @param string $header
+     */
     function _start_block($header) {
         echo $header;
     }
@@ -896,6 +933,9 @@ class _HWLDF_WordAccumulator {
         $this->_tag = $new_tag;
     }
 
+    /**
+     * @param string $new_tag
+     */
     function _flushLine($new_tag) {
         $this->_flushGroup($new_tag);
         if ($this->_line != '')
@@ -1055,6 +1095,10 @@ class TableDiffFormatter extends DiffFormatter {
         $this->trailing_context_lines = 2;
     }
 
+    /**
+     * @param Diff $diff
+     * @return string
+     */
     function format($diff) {
         // Preserve whitespaces by converting some to non-breaking spaces.
         // Do not convert all of them to allow word-wrap.
@@ -1165,6 +1209,10 @@ class InlineDiffFormatter extends DiffFormatter {
         $this->trailing_context_lines = 2;
     }
 
+    /**
+     * @param Diff $diff
+     * @return string
+     */
     function format($diff) {
         // Preserve whitespaces by converting some to non-breaking spaces.
         // Do not convert all of them to allow word-wrap.
diff --git a/inc/HTTPClient.php b/inc/HTTPClient.php
index ea20e3e56..2e991b52f 100644
--- a/inc/HTTPClient.php
+++ b/inc/HTTPClient.php
@@ -172,7 +172,8 @@ class HTTPClient {
      *
      * @param  string $url       The URL to fetch
      * @param  bool   $sloppy304 Return body on 304 not modified
-     * @return bool|string  response body, false on error
+     * @return false|string  response body, false on error
+     *
      * @author Andreas Gohr <andi@splitbrain.org>
      */
     function get($url,$sloppy304=false){
@@ -193,7 +194,8 @@ class HTTPClient {
      * @param  string $url       The URL to fetch
      * @param  array  $data      Associative array of parameters
      * @param  bool   $sloppy304 Return body on 304 not modified
-     * @return bool|string  response body, false on error
+     * @return false|string  response body, false on error
+     *
      * @author Andreas Gohr <andi@splitbrain.org>
      */
     function dget($url,$data,$sloppy304=false){
@@ -213,7 +215,7 @@ class HTTPClient {
      *
      * @param  string $url       The URL to fetch
      * @param  array  $data      Associative array of parameters
-     * @return bool|string  response body, false on error
+     * @return false|string  response body, false on error
      * @author Andreas Gohr <andi@splitbrain.org>
      */
     function post($url,$data){
@@ -235,6 +237,7 @@ class HTTPClient {
      * @param  mixed  $data   - the post data either as array or raw data
      * @param  string $method - HTTP Method usually GET or POST.
      * @return bool - true on success
+     *
      * @author Andreas Goetz <cpuidle@gmx.de>
      * @author Andreas Gohr <andi@splitbrain.org>
      */
@@ -602,6 +605,7 @@ class HTTPClient {
      * @param  string   $data       The data to write
      * @param  string   $message    Description of what is being read
      * @throws HTTPClientException
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     function _sendData($socket, $data, $message) {
@@ -646,6 +650,7 @@ class HTTPClient {
      * @param  bool     $ignore_eof End-of-file is not an error if this is set
      * @throws HTTPClientException
      * @return string
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     function _readData($socket, $nbytes, $message, $ignore_eof = false) {
@@ -695,6 +700,7 @@ class HTTPClient {
      * @param  string   $message    Description of what is being read
      * @throws HTTPClientException
      * @return string
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     function _readLine($socket, $message) {
@@ -729,6 +735,9 @@ class HTTPClient {
      * Uses _debug_text or _debug_html depending on the SAPI name
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $info
+     * @param mixed  $var
      */
     function _debug($info,$var=null){
         if(!$this->debug) return;
@@ -742,8 +751,8 @@ class HTTPClient {
     /**
      * print debug info as HTML
      *
-     * @param      $info
-     * @param null $var
+     * @param string $info
+     * @param mixed  $var
      */
     function _debug_html($info, $var=null){
         print '<b>'.$info.'</b> '.($this->_time() - $this->start).'s<br />';
@@ -759,8 +768,8 @@ class HTTPClient {
     /**
      * prints debug info as plain text
      *
-     * @param      $info
-     * @param null $var
+     * @param string $info
+     * @param mixed  $var
      */
     function _debug_text($info, $var=null){
         print '*'.$info.'* '.($this->_time() - $this->start)."s\n";
@@ -770,6 +779,8 @@ class HTTPClient {
 
     /**
      * Return current timestamp in microsecond resolution
+     *
+     * @return float
      */
     static function _time(){
         list($usec, $sec) = explode(" ", microtime());
@@ -782,6 +793,9 @@ class HTTPClient {
      * All Keys are lowercased.
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $string
+     * @return array
      */
     function _parseHeaders($string){
         $headers = array();
@@ -810,6 +824,9 @@ class HTTPClient {
      * convert given header array to header string
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param array $headers
+     * @return string
      */
     function _buildHeaders($headers){
         $string = '';
@@ -824,6 +841,8 @@ class HTTPClient {
      * get cookies as http header string
      *
      * @author Andreas Goetz <cpuidle@gmx.de>
+     *
+     * @return string
      */
     function _getCookies(){
         $headers = '';
@@ -839,6 +858,9 @@ class HTTPClient {
      * Encode data for posting
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param array $data
+     * @return string
      */
     function _postEncode($data){
         return http_build_query($data,'','&');
@@ -849,6 +871,9 @@ class HTTPClient {
      *
      * @fixme use of urlencode might be wrong here
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param array $data
+     * @return string
      */
     function _postMultipartEncode($data){
         $boundary = '--'.$this->boundary;
diff --git a/inc/IXR_Library.php b/inc/IXR_Library.php
index 2becf4a54..6ec397894 100644
--- a/inc/IXR_Library.php
+++ b/inc/IXR_Library.php
@@ -140,6 +140,10 @@ class IXR_Message {
     var $_lastseen;
     // The XML parser
     var $_parser;
+
+    /**
+     * @param string $message
+     */
     function IXR_Message ($message) {
         $this->message = $message;
     }
@@ -684,6 +688,13 @@ class IXR_IntrospectionServer extends IXR_Server {
             'Returns a documentation string for the specified method'
         );
     }
+
+    /**
+     * @param string   $method
+     * @param string   $callback
+     * @param string[] $args
+     * @param string   $help
+     */
     function addCallback($method, $callback, $args, $help) {
         $this->callbacks[$method] = $callback;
         $this->signatures[$method] = $args;
diff --git a/inc/Input.class.php b/inc/Input.class.php
index 94da2a10e..f4a4612df 100644
--- a/inc/Input.class.php
+++ b/inc/Input.class.php
@@ -83,7 +83,6 @@ class Input {
      *
      * @see isset
      * @param string $name Parameter name
-     * @return bool
      */
     public function remove($name) {
         if(isset($this->access[$name])) {
@@ -146,7 +145,7 @@ class Input {
      * Access a request parameter as int
      *
      * @param string    $name     Parameter name
-     * @param mixed     $default  Default to return if parameter isn't set or is an array
+     * @param int       $default  Default to return if parameter isn't set or is an array
      * @param bool      $nonempty Return $default if parameter is set but empty()
      * @return int
      */
@@ -164,7 +163,7 @@ class Input {
      * Access a request parameter as string
      *
      * @param string    $name     Parameter name
-     * @param mixed     $default  Default to return if parameter isn't set or is an array
+     * @param string    $default  Default to return if parameter isn't set or is an array
      * @param bool      $nonempty Return $default if parameter is set but empty()
      * @return string
      */
@@ -246,7 +245,7 @@ class Input {
      *
      * This function returns the $INPUT object itself for easy chaining
      *
-     * @param $name
+     * @param string $name
      * @return Input
      */
     public function extract($name){
diff --git a/inc/JpegMeta.php b/inc/JpegMeta.php
index 3b6c6694c..d50bad9b7 100644
--- a/inc/JpegMeta.php
+++ b/inc/JpegMeta.php
@@ -133,6 +133,9 @@ class JpegMeta {
      * through one function
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param array|string $fields field name or array with field names
+     * @return bool|string
      */
     function getField($fields) {
         if(!is_array($fields)) $fields = array($fields);
@@ -178,6 +181,10 @@ class JpegMeta {
      * through one function
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $field field name
+     * @param string $value
+     * @return bool success or fail
      */
     function setField($field, $value) {
         if(strtolower(substr($field,0,5)) == 'iptc.'){
@@ -194,6 +201,9 @@ class JpegMeta {
      * through one function
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $field field name
+     * @return bool
      */
     function deleteField($field) {
         if(strtolower(substr($field,0,5)) == 'iptc.'){
@@ -209,6 +219,9 @@ class JpegMeta {
      * Return a date field
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $field
+     * @return false|string
      */
     function getDateField($field) {
         if (!isset($this->_info['dates'])) {
@@ -226,6 +239,9 @@ class JpegMeta {
      * Return a file info field
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $field field name
+     * @return false|string
      */
     function getFileField($field) {
         if (!isset($this->_info['file'])) {
@@ -244,6 +260,8 @@ class JpegMeta {
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @todo   handle makernotes
+     *
+     * @return false|string
      */
     function getCamera(){
         $make  = $this->getField(array('Exif.Make','Exif.TIFFMake'));
@@ -257,6 +275,8 @@ class JpegMeta {
      * Return shutter speed as a ratio
      *
      * @author Joe Lapp <joe.lapp@pobox.com>
+     *
+     * @return string
      */
     function getShutterSpeed() {
         if (!isset($this->_info['exif'])) {
@@ -275,6 +295,9 @@ class JpegMeta {
      * Return an EXIF field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @return false|string
      */
     function getExifField($field) {
         if (!isset($this->_info['exif'])) {
@@ -296,6 +319,9 @@ class JpegMeta {
      * Return an XMP field
      *
      * @author Hakan Sandell <hakan.sandell@mydata.se>
+     *
+     * @param string $field field name
+     * @return false|string
      */
     function getXmpField($field) {
         if (!isset($this->_info['xmp'])) {
@@ -317,6 +343,9 @@ class JpegMeta {
      * Return an Adobe Field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @return false|string
      */
     function getAdobeField($field) {
         if (!isset($this->_info['adobe'])) {
@@ -338,6 +367,9 @@ class JpegMeta {
      * Return an IPTC field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @return false|string
      */
     function getIPTCField($field) {
         if (!isset($this->_info['iptc'])) {
@@ -360,6 +392,10 @@ class JpegMeta {
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
      * @author Joe Lapp <joe.lapp@pobox.com>
+     *
+     * @param string $field field name
+     * @param string $value
+     * @return bool
      */
     function setExifField($field, $value) {
         if (!isset($this->_info['exif'])) {
@@ -390,6 +426,10 @@ class JpegMeta {
      * Set an Adobe Field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @param string $value
+     * @return bool
      */
     function setAdobeField($field, $value) {
         if (!isset($this->_info['adobe'])) {
@@ -414,6 +454,10 @@ class JpegMeta {
      * dimensions
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param int $maxwidth
+     * @param int $maxheight
+     * @return float|int
      */
     function getResizeRatio($maxwidth,$maxheight=0){
         if(!$maxheight) $maxheight = $maxwidth;
@@ -443,6 +487,10 @@ class JpegMeta {
      * Set an IPTC field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @param string $value
+     * @return bool
      */
     function setIPTCField($field, $value) {
         if (!isset($this->_info['iptc'])) {
@@ -466,6 +514,9 @@ class JpegMeta {
      * Delete an EXIF field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @return bool
      */
     function deleteExifField($field) {
         if (!isset($this->_info['exif'])) {
@@ -487,6 +538,9 @@ class JpegMeta {
      * Delete an Adobe field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @return bool
      */
     function deleteAdobeField($field) {
         if (!isset($this->_info['adobe'])) {
@@ -508,6 +562,9 @@ class JpegMeta {
      * Delete an IPTC field
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $field field name
+     * @return bool
      */
     function deleteIPTCField($field) {
         if (!isset($this->_info['iptc'])) {
@@ -529,7 +586,7 @@ class JpegMeta {
      * Get the image's title, tries various fields
      *
      * @param int $max maximum number chars (keeps words)
-     * @return bool|mixed|string
+     * @return false|string
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      */
@@ -556,6 +613,8 @@ class JpegMeta {
      * Gather various date fields
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @return array|bool
      */
     function getDates() {
         $this->_parseAll();
@@ -692,6 +751,8 @@ class JpegMeta {
      * Get the image width, tries various fields
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @return false|string
      */
     function getWidth() {
         if (!isset($this->_info['sof'])) {
@@ -721,6 +782,8 @@ class JpegMeta {
      * Get the image height, tries various fields
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @return false|string
      */
     function getHeight() {
         if (!isset($this->_info['sof'])) {
@@ -750,6 +813,8 @@ class JpegMeta {
      * Get an dimension string for use in img tag
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @return false|string
      */
     function getDimStr() {
         if ($this->_markers == null) {
@@ -766,6 +831,9 @@ class JpegMeta {
      * Checks for an embedded thumbnail
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $which possible values: 'any', 'exif' or 'adobe'
+     * @return false|string
      */
     function hasThumbnail($which = 'any') {
         if (($which == 'any') || ($which == 'exif')) {
@@ -807,6 +875,9 @@ class JpegMeta {
      * Send embedded thumbnail to browser
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
+     *
+     * @param string $which possible values: 'any', 'exif' or 'adobe'
+     * @return bool
      */
     function sendThumbnail($which = 'any') {
         $data = null;
@@ -857,6 +928,9 @@ class JpegMeta {
      *
      * @author Sebastian Delmont <sdelmont@zonageek.com>
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $fileName file name or empty string for a random name
+     * @return bool
      */
     function save($fileName = "") {
         if ($fileName == "") {
diff --git a/inc/Mailer.class.php b/inc/Mailer.class.php
index fb9ed460c..087d82c99 100644
--- a/inc/Mailer.class.php
+++ b/inc/Mailer.class.php
@@ -108,6 +108,9 @@ class Mailer {
 
     /**
      * Callback function to automatically embed images referenced in HTML templates
+     *
+     * @param array $matches
+     * @return string placeholder
      */
     protected function autoembed_cb($matches) {
         static $embeds = 0;
@@ -160,6 +163,8 @@ class Mailer {
      *
      * Whatever is set here is directly passed to PHP's mail() command as last
      * parameter. Depending on the PHP setup this might break mailing alltogether
+     *
+     * @param string $param
      */
     public function setParameters($param) {
         $this->sendparam = $param;
@@ -265,6 +270,8 @@ class Mailer {
      * Placeholders can be used to reference embedded attachments
      *
      * You probably want to use setBody() instead
+     *
+     * @param string $html
      */
     public function setHTML($html) {
         $this->html = $html;
@@ -274,6 +281,8 @@ class Mailer {
      * Set the plain text part of the mail
      *
      * You probably want to use setBody() instead
+     *
+     * @param string $text
      */
     public function setText($text) {
         $this->text = $text;
@@ -340,8 +349,8 @@ class Mailer {
      * Example:
      *   cc("föö <foo@bar.com>, me@somewhere.com","TBcc");
      *
-     * @param string|array  $addresses Multiple adresses separated by commas or as array
-     * @return bool|string  the prepared header (can contain multiple lines)
+     * @param string|string[]  $addresses Multiple adresses separated by commas or as array
+     * @return false|string  the prepared header (can contain multiple lines)
      */
     public function cleanAddress($addresses) {
         // No named recipients for To: in Windows (see FS#652)
@@ -418,6 +427,8 @@ class Mailer {
      * Prepare the mime multiparts for all attachments
      *
      * Replaces placeholders in the HTML with the correct CIDs
+     *
+     * @return string mime multiparts
      */
     protected function prepareAttachments() {
         $mime = '';
@@ -565,9 +576,9 @@ class Mailer {
     /**
      * Returns a complete, EOL terminated header line, wraps it if necessary
      *
-     * @param $key
-     * @param $val
-     * @return string
+     * @param string $key
+     * @param string $val
+     * @return string line
      */
     protected function wrappedHeaderLine($key, $val){
         return wordwrap("$key: $val", 78, MAILHEADER_EOL.'  ').MAILHEADER_EOL;
diff --git a/inc/PassHash.class.php b/inc/PassHash.class.php
index db6a3a77c..15f896dcf 100644
--- a/inc/PassHash.class.php
+++ b/inc/PassHash.class.php
@@ -16,8 +16,9 @@ class PassHash {
      * match true is is returned else false
      *
      * @author  Andreas Gohr <andi@splitbrain.org>
-     * @param $clear string Clear-Text password
-     * @param $hash  string Hash to compare against
+     *
+     * @param string $clear Clear-Text password
+     * @param string $hash  Hash to compare against
      * @return  bool
      */
     function verify_hash($clear, $hash) {
@@ -109,9 +110,9 @@ class PassHash {
      * If $salt is not null, the value is kept, but the lenght restriction is
      * applied (unless, $cut is false).
      *
-     * @param string &$salt The salt, pass null if you want one generated
-     * @param int    $len   The length of the salt
-     * @param bool   $cut   Apply length restriction to existing salt?
+     * @param string|null &$salt  The salt, pass null if you want one generated
+     * @param int          $len   The length of the salt
+     * @param bool         $cut   Apply length restriction to existing salt?
      */
     public function init_salt(&$salt, $len = 32, $cut = true) {
         if(is_null($salt)) {
@@ -135,6 +136,7 @@ class PassHash {
      * @author Andreas Gohr <andi@splitbrain.org>
      * @author <mikey_nich at hotmail dot com>
      * @link   http://de.php.net/manual/en/function.crypt.php#73619
+     *
      * @param string $clear The clear text to hash
      * @param string $salt  The salt to use, null for random
      * @return string Hashed password
@@ -175,6 +177,7 @@ class PassHash {
      *
      * @author <mikey_nich at hotmail dot com>
      * @link   http://de.php.net/manual/en/function.crypt.php#73619
+     *
      * @param string $clear The clear text to hash
      * @param string $salt  The salt to use, null for random
      * @param string $magic The hash identifier (apr1 or 1)
@@ -337,6 +340,7 @@ class PassHash {
      * an exception.
      *
      * @link  http://www.openwall.com/phpass/
+     *
      * @param string $clear   The clear text to hash
      * @param string $salt    The salt to use, null for random
      * @param string $magic   The hash identifier (P or H)
@@ -404,6 +408,7 @@ class PassHash {
      * This is used by the Django Python framework
      *
      * @link http://docs.djangoproject.com/en/dev/topics/auth/#passwords
+     *
      * @param string $clear The clear text to hash
      * @param string $salt  The salt to use, null for random
      * @return string Hashed password
@@ -420,6 +425,7 @@ class PassHash {
      * This is used by the Django Python framework
      *
      * @link http://docs.djangoproject.com/en/dev/topics/auth/#passwords
+     *
      * @param string $clear The clear text to hash
      * @param string $salt  The salt to use, null for random
      * @return string Hashed password
@@ -486,6 +492,7 @@ class PassHash {
      * method 'A' is not supported.
      *
      * @link  http://www.mediawiki.org/wiki/Manual_talk:User_table#user_password_column
+     *
      * @param string $clear The clear text to hash
      * @param string $salt  The salt to use, null for random
      * @return string Hashed password
@@ -511,7 +518,6 @@ class PassHash {
      * @param string $data Message to be hashed.
      * @param string $key  Shared secret key used for generating the HMAC variant of the message digest.
      * @param bool $raw_output When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
-     *
      * @return string
      */
     public static function hmac($algo, $data, $key, $raw_output = false) {
@@ -545,9 +551,8 @@ class PassHash {
     /**
      * Use DokuWiki's secure random generator if available
      *
-     * @param $min
-     * @param $max
-     *
+     * @param int $min
+     * @param int $max
      * @return int
      */
     protected function random($min, $max){
diff --git a/inc/RemoteAPICore.php b/inc/RemoteAPICore.php
index 8c7a0e846..b34fe7f20 100644
--- a/inc/RemoteAPICore.php
+++ b/inc/RemoteAPICore.php
@@ -13,6 +13,11 @@ class RemoteAPICore {
         $this->api = $api;
     }
 
+    /**
+     * Returns details about the core methods
+     *
+     * @return array
+     */
     function __getRemoteInfo() {
         return array(
             'dokuwiki.getVersion' => array(
@@ -158,19 +163,27 @@ class RemoteAPICore {
         );
     }
 
+    /**
+     * @return string
+     */
     function getVersion() {
         return getVersion();
     }
 
+    /**
+     * @return int unix timestamp
+     */
     function getTime() {
         return time();
     }
 
     /**
      * Return a raw wiki page
+     *
      * @param string $id wiki page id
-     * @param string $rev revision number of the page
-     * @return page text.
+     * @param int|string $rev revision timestamp of the page or empty string
+     * @return string page text.
+     * @throws RemoteAccessDeniedException if no permission for page
      */
     function rawPage($id,$rev=''){
         $id = $this->resolvePageId($id);
@@ -189,8 +202,11 @@ class RemoteAPICore {
      * Return a media file
      *
      * @author Gina Haeussge <osd@foosel.net>
+     *
      * @param string $id file id
-     * @return media file
+     * @return mixed media file
+     * @throws RemoteAccessDeniedException no permission for media
+     * @throws RemoteException not exist
      */
     function getAttachment($id){
         $id = cleanID($id);
@@ -211,6 +227,9 @@ class RemoteAPICore {
      * Return info about a media file
      *
      * @author Gina Haeussge <osd@foosel.net>
+     *
+     * @param string $id page id
+     * @return array
      */
     function getAttachmentInfo($id){
         $id = cleanID($id);
@@ -230,6 +249,11 @@ class RemoteAPICore {
 
     /**
      * Return a wiki page rendered to html
+     *
+     * @param string     $id  page id
+     * @param string|int $rev revision timestamp or empty string
+     * @return null|string html
+     * @throws RemoteAccessDeniedException no access to page
      */
     function htmlPage($id,$rev=''){
         $id = $this->resolvePageId($id);
@@ -241,6 +265,8 @@ class RemoteAPICore {
 
     /**
      * List all pages - we use the indexer list here
+     *
+     * @return array
      */
     function listPages(){
         $list  = array();
@@ -265,6 +291,12 @@ class RemoteAPICore {
 
     /**
      * List all pages in the given namespace (and below)
+     *
+     * @param string $ns
+     * @param array  $opts
+     *    $opts['depth']   recursion level, 0 for all
+     *    $opts['hash']    do md5 sum of content?
+     * @return array
      */
     function readNamespace($ns,$opts){
         global $conf;
@@ -281,6 +313,9 @@ class RemoteAPICore {
 
     /**
      * List all pages in the given namespace (and below)
+     *
+     * @param string $query
+     * @return array
      */
     function search($query){
         $regex = '';
@@ -314,6 +349,8 @@ class RemoteAPICore {
 
     /**
      * Returns the wiki title.
+     *
+     * @return string
      */
     function getTitle(){
         global $conf;
@@ -328,6 +365,15 @@ class RemoteAPICore {
      * a regular expression matching their name.
      *
      * @author Gina Haeussge <osd@foosel.net>
+     *
+     * @param string $ns
+     * @param array  $options
+     *   $options['depth']     recursion level, 0 for all
+     *   $options['showmsg']   shows message if invalid media id is used
+     *   $options['pattern']   check given pattern
+     *   $options['hash']      add hashes to result list
+     * @return array
+     * @throws RemoteAccessDeniedException no access to the media files
      */
     function listAttachments($ns, $options = array()) {
         global $conf;
@@ -359,6 +405,9 @@ class RemoteAPICore {
 
     /**
      * Return a list of backlinks
+     *
+     * @param string $id page id
+     * @return array
      */
     function listBackLinks($id){
         return ft_backlinks($this->resolvePageId($id));
@@ -366,6 +415,12 @@ class RemoteAPICore {
 
     /**
      * Return some basic data about a page
+     *
+     * @param string     $id page id
+     * @param string|int $rev revision timestamp or empty string
+     * @return array
+     * @throws RemoteAccessDeniedException no access for page
+     * @throws RemoteException page not exist
      */
     function pageInfo($id,$rev=''){
         $id = $this->resolvePageId($id);
@@ -395,6 +450,13 @@ class RemoteAPICore {
      * Save a wiki page
      *
      * @author Michael Klier <chi@chimeric.de>
+     *
+     * @param string $id page id
+     * @param string $text wiki text
+     * @param array $params parameters: summary, minor edit
+     * @return bool
+     * @throws RemoteAccessDeniedException no write access for page
+     * @throws RemoteException no id, empty new page or locked
      */
     function putPage($id, $text, $params) {
         global $TEXT;
@@ -451,6 +513,11 @@ class RemoteAPICore {
 
     /**
      * Appends text to a wiki page.
+     *
+     * @param string $id page id
+     * @param string $text wiki text
+     * @param array $params such as summary,minor
+     * @return bool|string
      */
     function appendPage($id, $text, $params) {
         $currentpage = $this->rawPage($id);
@@ -464,6 +531,12 @@ class RemoteAPICore {
      * Uploads a file to the wiki.
      *
      * Michael Klier <chi@chimeric.de>
+     *
+     * @param string $id page id
+     * @param string $file
+     * @param array $params such as overwrite
+     * @return false|string
+     * @throws RemoteException
      */
     function putAttachment($id, $file, $params) {
         $id = cleanID($id);
@@ -493,6 +566,11 @@ class RemoteAPICore {
      * Deletes a file from the wiki.
      *
      * @author Gina Haeussge <osd@foosel.net>
+     *
+     * @param string $id page id
+     * @return int
+     * @throws RemoteAccessDeniedException no permissions
+     * @throws RemoteException file in use or not deleted
      */
     function deleteAttachment($id){
         $id = cleanID($id);
@@ -511,6 +589,9 @@ class RemoteAPICore {
 
     /**
      * Returns the permissions of a given wiki page
+     *
+     * @param string $id page id
+     * @return int permission level
      */
     function aclCheck($id) {
         $id = $this->resolvePageId($id);
@@ -521,6 +602,10 @@ class RemoteAPICore {
      * Lists all links contained in a wiki page
      *
      * @author Michael Klier <chi@chimeric.de>
+     *
+     * @param string $id page id
+     * @return array
+     * @throws RemoteAccessDeniedException  no read access for page
      */
     function listLinks($id) {
         $id = $this->resolvePageId($id);
@@ -571,6 +656,10 @@ class RemoteAPICore {
      *
      * @author Michael Hamann <michael@content-space.de>
      * @author Michael Klier <chi@chimeric.de>
+     *
+     * @param int $timestamp unix timestamp
+     * @return array
+     * @throws RemoteException no valid timestamp
      */
     function getRecentChanges($timestamp) {
         if(strlen($timestamp) != 10) {
@@ -596,7 +685,7 @@ class RemoteAPICore {
             return $changes;
         } else {
             // in case we still have nothing at this point
-            return new RemoteException('There are no changes in the specified timeframe', 321);
+            throw new RemoteException('There are no changes in the specified timeframe', 321);
         }
     }
 
@@ -605,6 +694,10 @@ class RemoteAPICore {
      *
      * @author Michael Hamann <michael@content-space.de>
      * @author Michael Klier <chi@chimeric.de>
+     *
+     * @param int $timestamp unix timestamp
+     * @return array
+     * @throws RemoteException no valid timestamp
      */
     function getRecentMediaChanges($timestamp) {
         if(strlen($timestamp) != 10)
@@ -637,6 +730,12 @@ class RemoteAPICore {
      * Returns a list of available revisions of a given wiki page
      *
      * @author Michael Klier <chi@chimeric.de>
+     *
+     * @param string $id    page id
+     * @param int    $first skip the first n changelog lines
+     * @return array
+     * @throws RemoteAccessDeniedException no read access for page
+     * @throws RemoteException empty id
      */
     function pageVersions($id, $first) {
         $id = $this->resolvePageId($id);
@@ -714,6 +813,9 @@ class RemoteAPICore {
      *
      * Returns an associative array with the keys locked, lockfail, unlocked and
      * unlockfail, each containing lists of pages.
+     *
+     * @param array[] $set list pages with array('lock' => array, 'unlock' => array)
+     * @return array
      */
     function setLocks($set){
         $locked     = array();
@@ -748,13 +850,27 @@ class RemoteAPICore {
         );
     }
 
+    /**
+     * Return API version
+     *
+     * @return int
+     */
     function getAPIVersion(){
         return DOKU_API_VERSION;
     }
 
+    /**
+     * Login
+     *
+     * @param string $user
+     * @param string $pass
+     * @return int
+     */
     function login($user,$pass){
         global $conf;
+        /** @var DokuWiki_Auth_Plugin $auth */
         global $auth;
+
         if(!$conf['useacl']) return 0;
         if(!$auth) return 0;
 
@@ -775,6 +891,11 @@ class RemoteAPICore {
         return $ok;
     }
 
+    /**
+     * Log off
+     *
+     * @return int
+     */
     function logoff(){
         global $conf;
         global $auth;
@@ -786,6 +907,12 @@ class RemoteAPICore {
         return 1;
     }
 
+    /**
+     * Resolve page id
+     *
+     * @param string $id page id
+     * @return string
+     */
     private function resolvePageId($id) {
         $id = cleanID($id);
         if(empty($id)) {
diff --git a/inc/Sitemapper.php b/inc/Sitemapper.php
index 33f6d7a36..0325f6d44 100644
--- a/inc/Sitemapper.php
+++ b/inc/Sitemapper.php
@@ -24,6 +24,8 @@ class Sitemapper {
      * @author Andreas Gohr
      * @link   https://www.google.com/webmasters/sitemaps/docs/en/about.html
      * @link   http://www.sitemaps.org/
+     *
+     * @return bool
      */
     public static function generate(){
         global $conf;
@@ -75,6 +77,7 @@ class Sitemapper {
      *
      * @param $items array The SitemapItems that shall be included in the sitemap.
      * @return string The sitemap XML.
+     *
      * @author Michael Hamann
      */
     private static function getXML($items) {
@@ -95,6 +98,7 @@ class Sitemapper {
      * Helper function for getting the path to the sitemap file.
      *
      * @return string The path to the sitemap file.
+     *
      * @author Michael Hamann
      */
     public static function getFilePath() {
@@ -123,6 +127,8 @@ class Sitemapper {
      * urls to ping using the SITEMAP_PING event.
      *
      * @author Michael Hamann
+     *
+     * @return bool
      */
     public static function pingSearchEngines() {
         //ping search engines...
@@ -168,9 +174,9 @@ class SitemapItem {
     /**
      * Create a new item.
      *
-     * @param $url string The url of the item
-     * @param $lastmod int Timestamp of the last modification
-     * @param $changefreq string How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never.
+     * @param string $url        The url of the item
+     * @param int    $lastmod    Timestamp of the last modification
+     * @param string $changefreq How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never.
      * @param $priority float|string The priority of the item relative to other URLs on your site. Valid values range from 0.0 to 1.0.
      */
     public function __construct($url, $lastmod, $changefreq = null, $priority = null) {
@@ -183,9 +189,9 @@ class SitemapItem {
     /**
      * Helper function for creating an item for a wikipage id.
      *
-     * @param $id string A wikipage id.
-     * @param $changefreq string How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never.
-     * @param $priority float|string The priority of the item relative to other URLs on your site. Valid values     range from 0.0 to 1.0.
+     * @param string       $id         A wikipage id.
+     * @param string       $changefreq How frequently the item is likely to change. Valid values: always, hourly, daily, weekly, monthly, yearly, never.
+     * @param float|string $priority   The priority of the item relative to other URLs on your site. Valid values     range from 0.0 to 1.0.
      * @return SitemapItem The sitemap item.
      */
     public static function createFromID($id, $changefreq = null, $priority = null) {
diff --git a/inc/Tar.class.php b/inc/Tar.class.php
index 8c7d33fc1..05831df58 100644
--- a/inc/Tar.class.php
+++ b/inc/Tar.class.php
@@ -105,6 +105,9 @@ class Tar {
      *
      * The archive is closed afer reading the contents, because rewinding is not possible in bzip2 streams.
      * Reopen the file with open() again if you want to do additional operations
+     *
+     * @return array
+     * @throws TarIOException
      */
     public function contents() {
         if($this->closed || !$this->file) throw new TarIOException('Can not read from a closed archive');
@@ -270,6 +273,7 @@ class Tar {
      * Add a file to the current TAR archive using an existing file in the filesystem
      *
      * @todo handle directory adding
+     *
      * @param string $file the original file
      * @param string $name the name to use for the file in the archive
      * @throws TarIOException
@@ -377,6 +381,10 @@ class Tar {
      * Returns the created in-memory archive data
      *
      * This implicitly calls close() on the Archive
+     *
+     * @param int $comptype
+     * @param int $complevel
+     * @return mixed|string
      */
     public function getArchive($comptype = Tar::COMPRESS_AUTO, $complevel = 9) {
         $this->close();
@@ -395,7 +403,7 @@ class Tar {
      * Note: It more memory effective to specify the filename in the create() function and
      * let the library work on the new file directly.
      *
-     * @param     $file
+     * @param string $file
      * @param int $comptype
      * @param int $complevel
      * @throws TarIOException
@@ -571,7 +579,7 @@ class Tar {
     /**
      * Cleans up a path and removes relative parts, also strips leading slashes
      *
-     * @param string $p_dir
+     * @param string $path
      * @return string
      */
     public function cleanPath($path) {
@@ -591,7 +599,7 @@ class Tar {
     /**
      * Checks if the given compression type is available and throws an exception if not
      *
-     * @param $comptype
+     * @param int $comptype
      * @throws TarIllegalCompressionException
      */
     protected function compressioncheck($comptype) {
diff --git a/inc/actions.php b/inc/actions.php
index 5cf63a6ca..68b71a36a 100644
--- a/inc/actions.php
+++ b/inc/actions.php
@@ -221,6 +221,9 @@ function act_sendheaders($headers) {
  * Sanitize the action command
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array|string $act
+ * @return string
  */
 function act_clean($act){
     // check if the action was given as array key
@@ -245,6 +248,9 @@ function act_clean($act){
  * Add all allowed commands here.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array|string $act
+ * @return string
  */
 function act_validate($act) {
     global $conf;
@@ -284,10 +290,12 @@ function act_validate($act) {
  * Run permissionchecks
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_permcheck($act){
     global $INFO;
-    global $conf;
 
     if(in_array($act,array('save','preview','edit','recover'))){
         if($INFO['exists']){
@@ -330,6 +338,9 @@ function act_permcheck($act){
  * Handle 'draftdel'
  *
  * Deletes the draft for the current page and user
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_draftdel($act){
     global $INFO;
@@ -342,6 +353,9 @@ function act_draftdel($act){
  * Saves a draft on preview
  *
  * @todo this currently duplicates code from ajax.php :-/
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_draftsave($act){
     global $INFO;
@@ -372,6 +386,9 @@ function act_draftsave($act){
  * returns a new action.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_save($act){
     global $ID;
@@ -410,6 +427,9 @@ function act_save($act){
  * Revert to a certain revision
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_revert($act){
     global $ID;
@@ -457,6 +477,9 @@ function act_revert($act){
  * Do a redirect after receiving post data
  *
  * Tries to add the section id as hash mark after section editing
+ *
+ * @param string $id page id
+ * @param string $preact action command before redirect
  */
 function act_redirect($id,$preact){
     global $PRE;
@@ -478,7 +501,7 @@ function act_redirect($id,$preact){
 /**
  * Execute the redirect
  *
- * @param array $opts id and fragment for the redirect
+ * @param array $opts id and fragment for the redirect and the preact
  */
 function act_redirect_execute($opts){
     $go = wl($opts['id'],'',true);
@@ -492,6 +515,9 @@ function act_redirect_execute($opts){
  * Handle 'login', 'logout'
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_auth($act){
     global $ID;
@@ -527,6 +553,9 @@ function act_auth($act){
  * Handle 'edit', 'preview', 'recover'
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_edit($act){
     global $ID;
@@ -591,6 +620,9 @@ function act_edit($act){
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Michael Klier <chi@chimeric.de>
+ *
+ * @param string $act action command
+ * @return string action command
  */
 function act_export($act){
     global $ID;
@@ -671,6 +703,8 @@ function act_export($act){
  * Handle sitemap delivery
  *
  * @author Michael Hamann <michael@content-space.de>
+ *
+ * @param string $act action command
  */
 function act_sitemap($act) {
     global $conf;
@@ -719,6 +753,10 @@ function act_sitemap($act) {
  * Throws exception on error.
  *
  * @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @param string $act action command
+ * @return string action command
+ * @throws Exception if (un)subscribing fails
  */
 function act_subscription($act){
     global $lang;
@@ -778,6 +816,9 @@ function act_subscription($act){
  * default action for the event ACTION_HANDLE_SUBSCRIBE.
  *
  * @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @param array &$params the parameters: target, style and action
+ * @throws Exception
  */
 function subscription_handle_post(&$params) {
     global $INFO;
diff --git a/inc/auth.php b/inc/auth.php
index dc2b6cad8..3a6a2f65a 100644
--- a/inc/auth.php
+++ b/inc/auth.php
@@ -127,6 +127,7 @@ function auth_setup() {
  * Loads the ACL setup and handle user wildcards
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @return array
  */
 function auth_loadACL() {
@@ -173,7 +174,7 @@ function auth_loadACL() {
 /**
  * Event hook callback for AUTH_LOGIN_CHECK
  *
- * @param $evdata
+ * @param array $evdata
  * @return bool
  */
 function auth_login_wrapper($evdata) {
@@ -280,6 +281,7 @@ function auth_login($user, $pass, $sticky = false, $silent = false) {
  * token is correct. Will exit with a 401 Status if not.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param  string $token The authentication token
  * @return boolean true (or will exit on failure)
  */
@@ -307,6 +309,7 @@ function auth_validateToken($token) {
  * NOTE: this is completely unrelated to the getSecurityToken() function
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @return string The auth token
  */
 function auth_createToken() {
@@ -351,6 +354,7 @@ function auth_browseruid() {
  * and stored in this file.
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @param   bool $addsession if true, the sessionid is added to the salt
  * @param   bool $secure     if security is more important than keeping the old value
  * @return  string
@@ -378,6 +382,7 @@ function auth_cookiesalt($addsession = false, $secure = false) {
  * @author Mark Seecof
  * @author Michael Hamann <michael@content-space.de>
  * @link   http://www.php.net/manual/de/function.mt-rand.php#83655
+ *
  * @param int $length number of bytes to get
  * @return string binary random strings
  */
@@ -444,6 +449,7 @@ function auth_randombytes($length) {
  *
  * @author Michael Samuel
  * @author Michael Hamann <michael@content-space.de>
+ *
  * @param int $min
  * @param int $max
  * @return int
@@ -515,6 +521,7 @@ function auth_decrypt($ciphertext, $secret) {
  * off. It also clears session data.
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @param bool $keepbc - when true, the breadcrumb data is not cleared
  */
 function auth_logoff($keepbc = false) {
@@ -555,6 +562,7 @@ function auth_logoff($keepbc = false) {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @see    auth_isadmin
+ *
  * @param  string $user       Username
  * @param  array  $groups     List of groups the user is in
  * @param  bool   $adminonly  when true checks if user is admin
@@ -599,6 +607,7 @@ function auth_ismanager($user = null, $groups = null, $adminonly = false) {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @see auth_ismanager()
+ *
  * @param  string $user       Username
  * @param  array  $groups     List of groups the user is in
  * @return bool
@@ -613,9 +622,9 @@ function auth_isadmin($user = null, $groups = null) {
  *
  * Note: all input should NOT be nameencoded.
  *
- * @param $memberlist string commaseparated list of allowed users and groups
- * @param $user       string user to match against
- * @param $groups     array  groups the user is member of
+ * @param string $memberlist commaseparated list of allowed users and groups
+ * @param string $user       user to match against
+ * @param array  $groups     groups the user is member of
  * @return bool       true for membership acknowledged
  */
 function auth_isMember($memberlist, $user, array $groups) {
@@ -678,6 +687,7 @@ function auth_quickaclcheck($id) {
  * Returns the maximum rights a user has for the given ID or its namespace
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @triggers AUTH_ACL_CHECK
  * @param  string       $id     page ID (needs to be resolved and cleaned)
  * @param  string       $user   Username
@@ -700,6 +710,7 @@ function auth_aclcheck($id, $user, $groups) {
  * DO NOT CALL DIRECTLY, use auth_aclcheck() instead
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @param  array $data event data
  * @return int   permission level
  */
@@ -832,6 +843,10 @@ function auth_aclcheck_cb($data) {
  *
  * @author Andreas Gohr <gohr@cosmocode.de>
  * @see rawurldecode()
+ *
+ * @param string $name
+ * @param bool $skip_group
+ * @return string
  */
 function auth_nameencode($name, $skip_group = false) {
     global $cache_authname;
@@ -913,6 +928,7 @@ function auth_pwgen($foruser = '') {
  * Sends a password to the given user
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $user Login name of the user
  * @param string $password The new password in clear text
  * @return bool  true on success
@@ -948,6 +964,7 @@ function auth_sendPassword($user, $password) {
  * This registers a new user - Data is read directly from $_POST
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @return bool  true on success, false on any error
  */
 function register() {
@@ -1280,6 +1297,7 @@ function act_resendpwd() {
  * is chosen.
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $clear The clear text password
  * @param string $method The hashing method
  * @param string $salt A salt, null for random
@@ -1304,6 +1322,7 @@ function auth_cryptPassword($clear, $method = '', $salt = null) {
  * Verifies a cleartext password against a crypted hash
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param  string $clear The clear text password
  * @param  string $crypt The hash to compare with
  * @return bool true if both match
diff --git a/inc/blowfish.php b/inc/blowfish.php
index bcf5804a2..7499515bc 100644
--- a/inc/blowfish.php
+++ b/inc/blowfish.php
@@ -356,7 +356,7 @@ class Horde_Cipher_blowfish
      * Encrypt a block on data.
      *
      * @param String $block         The data to encrypt
-     * @param optional String $key  The key to use
+     * @param String $key  optional The key to use
      *
      * @return String the encrypted output
      */
@@ -404,8 +404,8 @@ class Horde_Cipher_blowfish
     /**
      * Decrypt a block on data.
      *
-     * @param String $block         The data to decrypt
-     * @param optional String $key  The key to use
+     * @param String $block          The data to decrypt
+     * @param String $key   optional The key to use
      *
      * @return String the decrypted output
      */
@@ -452,6 +452,7 @@ class Horde_Cipher_blowfish
     /**
      * Converts a text key into an array.
      *
+     * @param string $key
      * @return array  The key.
      */
     function _formatKey($key) {
@@ -464,8 +465,8 @@ class Horde_Cipher_blowfish
 /**
  * Encryption using blowfish algorithm
  *
- * @param   string  original data
- * @param   string  the secret
+ * @param   string  $data   original data
+ * @param   string  $secret the secret
  *
  * @return  string  the encrypted result
  *
@@ -493,8 +494,8 @@ function PMA_blowfish_encrypt($data, $secret) {
 /**
  * Decryption using blowfish algorithm
  *
- * @param   string  encrypted data
- * @param   string  the secret
+ * @param   string  $encdata encrypted data
+ * @param   string  $secret  the secret
  *
  * @return  string  original data
  *
diff --git a/inc/changelog.php b/inc/changelog.php
index 8c14f21b0..e2826e4b3 100644
--- a/inc/changelog.php
+++ b/inc/changelog.php
@@ -725,8 +725,10 @@ abstract class ChangeLog {
      * If file larger than $chuncksize, only chunck is read that could contain $rev.
      *
      * @param int $rev   revision timestamp
-     * @return array(fp, array(changeloglines), $head, $tail, $eof)|bool
-     *     returns false when not succeed. fp only defined for chuck reading, needs closing.
+     * @return array|false
+     *     if success returns array(fp, array(changeloglines), $head, $tail, $eof)
+     *     where fp only defined for chuck reading, needs closing.
+     *     otherwise false
      */
     protected function readloglines($rev) {
         $file = $this->getChangelogFilename();
diff --git a/inc/cli.php b/inc/cli.php
index 25bfddf7d..29d76ece1 100644
--- a/inc/cli.php
+++ b/inc/cli.php
@@ -108,7 +108,7 @@ abstract class DokuCLI {
     /**
      * Print an error message
      *
-     * @param $string
+     * @param string $string
      */
     public function error($string) {
         $this->colors->ptln("E: $string", 'red', STDERR);
@@ -117,7 +117,7 @@ abstract class DokuCLI {
     /**
      * Print a success message
      *
-     * @param $string
+     * @param string $string
      */
     public function success($string) {
         $this->colors->ptln("S: $string", 'green', STDERR);
@@ -126,7 +126,7 @@ abstract class DokuCLI {
     /**
      * Print an info message
      *
-     * @param $string
+     * @param string $string
      */
     public function info($string) {
         $this->colors->ptln("I: $string", 'cyan', STDERR);
@@ -199,8 +199,8 @@ class DokuCLI_Colors {
     /**
      * Convenience function to print a line in a given color
      *
-     * @param          $line
-     * @param          $color
+     * @param string   $line
+     * @param string   $color
      * @param resource $channel
      */
     public function ptln($line, $color, $channel = STDOUT) {
@@ -470,8 +470,8 @@ class DokuCLI_Options {
      * Can only be used after parseOptions() has been run
      *
      * @param string $option
-     * @param mixed  $default what to return if the option was not set
-     * @return mixed
+     * @param bool|string $default what to return if the option was not set
+     * @return false|string
      */
     public function getOpt($option, $default = false) {
         if(isset($this->options[$option])) return $this->options[$option];
@@ -593,8 +593,8 @@ class DokuCLI_Options {
     /**
      * Displays text in multiple word wrapped columns
      *
-     * @param array $widths list of column widths (in characters)
-     * @param array $texts  list of texts for each column
+     * @param int[]    $widths list of column widths (in characters)
+     * @param string[] $texts  list of texts for each column
      * @return string
      */
     private function tableFormat($widths, $texts) {
@@ -640,6 +640,11 @@ class DokuCLI_Exception extends Exception {
     const E_OPT_ABIGUOUS = 4; //Option abiguous
     const E_ARG_READ = 5; //Could not read argv
 
+    /**
+     * @param string    $message     The Exception message to throw.
+     * @param int       $code        The Exception code
+     * @param Exception $previous    The previous exception used for the exception chaining.
+     */
     public function __construct($message = "", $code = 0, Exception $previous = null) {
         if(!$code) $code = DokuCLI_Exception::E_ANY;
         parent::__construct($message, $code, $previous);
diff --git a/inc/common.php b/inc/common.php
index 91a068bb0..444e90198 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -49,7 +49,7 @@ function ptln($string, $indent = 0) {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  *
- * @param $string string being stripped
+ * @param string $string being stripped
  * @return string
  */
 function stripctl($string) {
@@ -62,6 +62,7 @@ function stripctl($string) {
  * @author  Andreas Gohr <andi@splitbrain.org>
  * @link    http://en.wikipedia.org/wiki/Cross-site_request_forgery
  * @link    http://christ1an.blogspot.com/2007/04/preventing-csrf-efficiently.html
+ *
  * @return  string
  */
 function getSecurityToken() {
@@ -95,7 +96,7 @@ function checkSecurityToken($token = null) {
  * @author  Andreas Gohr <andi@splitbrain.org>
  *
  * @param bool $print  if true print the field, otherwise html of the field is returned
- * @return void|string html of hidden form field
+ * @return string html of hidden form field
  */
 function formSecurityToken($print = true) {
     $ret = '<div class="no"><input type="hidden" name="sectok" value="'.getSecurityToken().'" /></div>'."\n";
@@ -336,7 +337,7 @@ function buildAttributes($params, $skipempty = false) {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  *
- * @return array(pageid=>name, ... )
+ * @return string[string] with the data: array(pageid=>name, ... )
  */
 function breadcrumbs() {
     // we prepare the breadcrumbs early for quick session closing
@@ -1110,7 +1111,7 @@ function parsePageTemplate(&$data) {
  * @param string $range in form "from-to"
  * @param string $id    page id
  * @param string $rev   optional, the revision timestamp
- * @return array with three slices
+ * @return string[] with three slices
  */
 function rawWikiSlices($range, $id, $rev = '') {
     $text = io_readWikiPage(wikiFN($id, $rev), $id, $rev);
@@ -1296,7 +1297,7 @@ function saveOldRevision($id) {
  * @param int|string $rev Old page revision
  * @param string     $summary  What changed
  * @param boolean    $minor    Is this a minor edit?
- * @param array      $replace  Additional string substitutions, @KEY@ to be replaced by value
+ * @param string[]   $replace  Additional string substitutions, @KEY@ to be replaced by value
  * @return bool
  *
  * @author Andreas Gohr <andi@splitbrain.org>
@@ -1376,8 +1377,8 @@ function getGoogleQuery() {
 /**
  * Return the human readable size of a file
  *
- * @param       int $size A file size
- * @param       int $dec A number of decimal places
+ * @param int $size A file size
+ * @param int $dec A number of decimal places
  * @return string human readable size
  *
  * @author      Martin Benjamin <b.martin@cybernet.ch>
@@ -1914,7 +1915,7 @@ function set_doku_pref($pref, $val) {
 /**
  * Strips source mapping declarations from given text #601
  *
- * @param &string $text reference to the CSS or JavaScript code to clean
+ * @param string &$text reference to the CSS or JavaScript code to clean
  */
 function stripsourcemaps(&$text){
     $text = preg_replace('/^(\/\/|\/\*)[@#]\s+sourceMappingURL=.*?(\*\/)?$/im', '\\1\\2', $text);
diff --git a/inc/confutils.php b/inc/confutils.php
index 31371d41f..85bf5128c 100644
--- a/inc/confutils.php
+++ b/inc/confutils.php
@@ -14,6 +14,10 @@
  * are returned.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file file name
+ * @param bool   $knownonly
+ * @return array with extension, mimetype and if it should be downloaded
  */
 function mimetype($file, $knownonly=true){
     $mtypes = getMimeTypes();     // known mimetypes
diff --git a/inc/events.php b/inc/events.php
index 318a7617e..4cd06b9f9 100644
--- a/inc/events.php
+++ b/inc/events.php
@@ -165,13 +165,13 @@ class Doku_Event_Handler {
      *
      * register a hook for an event
      *
-     * @param  $event   string   name used by the event, (incl '_before' or '_after' for triggers)
-     * @param  $advise  string
-     * @param  $obj     object   object in whose scope method is to be executed,
+     * @param  string   $event   string   name used by the event, (incl '_before' or '_after' for triggers)
+     * @param  string   $advise
+     * @param  object   $obj     object in whose scope method is to be executed,
      *                             if NULL, method is assumed to be a globally available function
-     * @param  $method  string   event handler function
-     * @param  $param   mixed    data passed to the event handler
-     * @param  $seq     int      sequence number for ordering hook execution (ascending)
+     * @param  string   $method  event handler function
+     * @param  mixed    $param   data passed to the event handler
+     * @param  int      $seq     sequence number for ordering hook execution (ascending)
      */
     function register_hook($event, $advise, $obj, $method, $param=null, $seq=0) {
         $seq = (int)$seq;
@@ -216,14 +216,14 @@ class Doku_Event_Handler {
  *
  * function wrapper to process (create, trigger and destroy) an event
  *
- * @param  $name               string   name for the event
- * @param  $data               mixed    event data
- * @param  $action             callback (optional, default=NULL) default action, a php callback function
- * @param  $canPreventDefault  bool     (optional, default=true) can hooks prevent the default action
+ * @param  string   $name               name for the event
+ * @param  mixed    $data               event data
+ * @param  callback $action             (optional, default=NULL) default action, a php callback function
+ * @param  bool     $canPreventDefault  (optional, default=true) can hooks prevent the default action
  *
  * @return mixed                        the event results value after all event processing is complete
- *                                         by default this is the return value of the default action however
- *                                         it can be set or modified by event handler hooks
+ *                                      by default this is the return value of the default action however
+ *                                      it can be set or modified by event handler hooks
  */
 function trigger_event($name, &$data, $action=null, $canPreventDefault=true) {
 
diff --git a/inc/fetch.functions.php b/inc/fetch.functions.php
index c61c54503..70becc01e 100644
--- a/inc/fetch.functions.php
+++ b/inc/fetch.functions.php
@@ -16,6 +16,7 @@
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Ben Coburn <btcoburn@silicodon.net>
  * @author Gerry Weissbach <dokuwiki@gammaproduction.de>
+ *
  * @param string $file   local file to send
  * @param string $mime   mime type of the file
  * @param bool   $dl     set to true to force a browser download
@@ -96,12 +97,13 @@ function sendFile($file, $mime, $dl, $cache, $public = false, $orig = null) {
  * WRITE: MEDIA, FILE, array( STATUS, STATUSMESSAGE )
  *
  * @author Gerry Weissbach <gerry.w@gammaproduction.de>
+ *
  * @param string $media  reference to the media id
  * @param string $file   reference to the file variable
  * @param string $rev
  * @param int    $width
  * @param int    $height
- * @return array(STATUS, STATUSMESSAGE)
+ * @return array as array(STATUS, STATUSMESSAGE)
  */
 function checkFileStatus(&$media, &$file, $rev = '', $width=0, $height=0) {
     global $MIME, $EXT, $CACHE, $INPUT;
@@ -149,6 +151,9 @@ function checkFileStatus(&$media, &$file, $rev = '', $width=0, $height=0) {
  * Resolves named constants
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $cache
+ * @return int cachetime in seconds
  */
 function calc_cache($cache) {
     global $conf;
diff --git a/inc/form.php b/inc/form.php
index fadc71d3e..00eea9b3a 100644
--- a/inc/form.php
+++ b/inc/form.php
@@ -52,6 +52,7 @@ class Doku_Form {
      * @param bool|string $action  (optional, deprecated) submit URL, defaults to current page
      * @param bool|string $method  (optional, deprecated) 'POST' or 'GET', default is POST
      * @param bool|string $enctype (optional, deprecated) Encoding type of the data
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function Doku_Form($params, $action=false, $method=false, $enctype=false) {
@@ -84,6 +85,7 @@ class Doku_Form {
      * Usually results in a border drawn around the form.
      *
      * @param   string  $legend Label that will be printed with the border.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function startFieldset($legend) {
@@ -115,6 +117,7 @@ class Doku_Form {
      *
      * @param   string  $name   Field name.
      * @param   string  $value  Field value. If null, remove a previously added field.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function addHidden($name, $value) {
@@ -132,6 +135,7 @@ class Doku_Form {
      * If string, it is printed without escaping special chars.   *
      *
      * @param   string|array  $elem   Pseudo-tag or string to add to the form.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function addElement($elem) {
@@ -145,6 +149,7 @@ class Doku_Form {
      *
      * @param   string       $pos  0-based index where the element will be inserted.
      * @param   string|array $elem Pseudo-tag or string to add to the form.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function insertElement($pos, $elem) {
@@ -158,6 +163,7 @@ class Doku_Form {
      *
      * @param   int          $pos  0-based index the element will be placed at.
      * @param   string|array $elem Pseudo-tag or string to add to the form.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function replaceElement($pos, $elem) {
@@ -172,7 +178,8 @@ class Doku_Form {
      * Gets the position of the first of a type of element.
      *
      * @param   string  $type   Element type to look for.
-     * @return  int     position of element if found, otherwise false
+     * @return  int|false     position of element if found, otherwise false
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function findElementByType($type) {
@@ -189,7 +196,8 @@ class Doku_Form {
      * Gets the position of the element with an ID attribute.
      *
      * @param   string  $id     ID of the element to find.
-     * @return  int     position of element if found, otherwise false
+     * @return  int|false     position of element if found, otherwise false
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function findElementById($id) {
@@ -207,7 +215,8 @@ class Doku_Form {
      *
      * @param   string  $name   Attribute name.
      * @param   string  $value  Attribute value.
-     * @return  int     position of element if found, otherwise false
+     * @return  int|false     position of element if found, otherwise false
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function findElementByAttribute($name, $value) {
@@ -227,6 +236,7 @@ class Doku_Form {
      *
      * @param   int     $pos    0-based index
      * @return  array reference  pseudo-element
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function &getElementAt($pos) {
@@ -243,6 +253,8 @@ class Doku_Form {
      * 'form_$type'. The function should return the HTML to be printed.
      *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
+     *
+     * @return string html of the form
      */
     function getForm() {
         global $lang;
@@ -310,6 +322,7 @@ class Doku_Form {
  * @param   string  $tag    Tag name.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeTag($tag, $attrs=array()) {
@@ -326,6 +339,7 @@ function form_makeTag($tag, $attrs=array()) {
  * @param   string  $tag    Tag name.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeOpenTag($tag, $attrs=array()) {
@@ -341,6 +355,7 @@ function form_makeOpenTag($tag, $attrs=array()) {
  *
  * @param   string  $tag    Tag name.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeCloseTag($tag) {
@@ -358,6 +373,7 @@ function form_makeCloseTag($tag) {
  * @param   string  $text   Text to fill the field with.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeWikiText($text, $attrs=array()) {
@@ -378,6 +394,7 @@ function form_makeWikiText($text, $attrs=array()) {
  * @param   string  $value  (optional) Displayed label. Uses $act if not provided.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeButton($type, $act, $value='', $attrs=array()) {
@@ -406,6 +423,7 @@ function form_makeButton($type, $act, $value='', $attrs=array()) {
  *                          reference it with a 'for' attribute.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeField($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) {
@@ -522,6 +540,18 @@ function form_makeRadioField($name, $value='1', $label=null, $id='', $class='',
  * a string.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string           $name     Name attribute of the input.
+ * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
+ *                                   or an associative array with the values as keys and labels as values.
+ * @param string|int       $selected default selected value, string or index number
+ * @param string           $class    Class attribute of the label. If this is 'block',
+ *                                   then a line break will be added after the field.
+ * @param string           $label    Label that will be printed before the input.
+ * @param string           $id       ID attribute of the input. If set, the label will
+ *                                   reference it with a 'for' attribute.
+ * @param array            $attrs    Optional attributes.
+ * @return array   pseudo-tag
  */
 function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
     if (is_null($label)) $label = $name;
@@ -556,6 +586,18 @@ function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $
  * Items are selected by supplying its value or an array of values.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string           $name     Name attribute of the input.
+ * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
+ *                                   or an associative array with the values as keys and labels as values.
+ * @param array|string     $selected value or array of values of the items that need to be selected
+ * @param string           $class    Class attribute of the label. If this is 'block',
+ *                                   then a line break will be added after the field.
+ * @param string           $label    Label that will be printed before the input.
+ * @param string           $id       ID attribute of the input. If set, the label will
+ *                                   reference it with a 'for' attribute.
+ * @param array            $attrs    Optional attributes.
+ * @return array   pseudo-tag
  */
 function form_makeListboxField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
     if (is_null($label)) $label = $name;
@@ -595,6 +637,9 @@ function form_makeListboxField($name, $values, $selected='', $label=null, $id=''
  * Attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
  */
 function form_tag($attrs) {
     return '<'.$attrs['_tag'].' '.buildAttributes($attrs,true).'/>';
@@ -608,6 +653,9 @@ function form_tag($attrs) {
  * Attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
  */
 function form_opentag($attrs) {
     return '<'.$attrs['_tag'].' '.buildAttributes($attrs,true).'>';
@@ -621,6 +669,9 @@ function form_opentag($attrs) {
  * There are no attributes.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
  */
 function form_closetag($attrs) {
     return '</'.$attrs['_tag'].'>';
@@ -634,6 +685,9 @@ function form_closetag($attrs) {
  * Attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_openfieldset($attrs) {
     $s = '<fieldset '.buildAttributes($attrs,true).'>';
@@ -648,6 +702,8 @@ function form_openfieldset($attrs) {
  * There are no attributes.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @return string html
  */
 function form_closefieldset() {
     return '</fieldset>';
@@ -661,6 +717,9 @@ function form_closefieldset() {
  * Value is passed to formText()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_hidden($attrs) {
     return '<input type="hidden" name="'.$attrs['name'].'" value="'.formText($attrs['value']).'" />';
@@ -674,6 +733,9 @@ function form_hidden($attrs) {
  * Text will be passed to formText(), attributes to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_wikitext($attrs) {
     // mandatory attributes
@@ -693,6 +755,9 @@ function form_wikitext($attrs) {
  * Other attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_button($attrs) {
     $p = (!empty($attrs['_action'])) ? 'name="do['.$attrs['_action'].']" ' : '';
@@ -708,6 +773,9 @@ function form_button($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_field($attrs) {
     $s = '<label';
@@ -729,6 +797,9 @@ function form_field($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_fieldright($attrs) {
     $s = '<label';
@@ -750,6 +821,9 @@ function form_fieldright($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_textfield($attrs) {
     // mandatory attributes
@@ -773,6 +847,9 @@ function form_textfield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_passwordfield($attrs) {
     // mandatory attributes
@@ -798,6 +875,9 @@ function form_passwordfield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag
  *
  * @author  Michael Klier <chi@chimeric.de>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_filefield($attrs) {
     $s = '<label';
@@ -824,6 +904,9 @@ function form_filefield($attrs) {
  * $attrs['value'][1] is constructed as well.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_checkboxfield($attrs) {
     // mandatory attributes
@@ -853,6 +936,9 @@ function form_checkboxfield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_radiofield($attrs) {
     // mandatory attributes
@@ -879,6 +965,9 @@ function form_radiofield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_menufield($attrs) {
     $attrs['size'] = '1';
@@ -924,6 +1013,9 @@ function form_menufield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_listboxfield($attrs) {
     $s = '<label';
diff --git a/inc/fulltext.php b/inc/fulltext.php
index c1dc16e47..d6cddc566 100644
--- a/inc/fulltext.php
+++ b/inc/fulltext.php
@@ -20,6 +20,9 @@ if(!defined('FT_SNIPPET_NUMBER')) define('FT_SNIPPET_NUMBER',15);
  *
  * refactored into ft_pageSearch(), _ft_pageSearch() and trigger_event()
  *
+ * @param string $query
+ * @param array $highlight
+ * @return array
  */
 function ft_pageSearch($query,&$highlight){
 
@@ -35,6 +38,9 @@ function ft_pageSearch($query,&$highlight){
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Kazutaka Miyasaka <kazmiya@gmail.com>
+ *
+ * @param array $data event data
+ * @return array matching documents
  */
 function _ft_pageSearch(&$data) {
     $Indexer = idx_get_indexer();
@@ -206,6 +212,11 @@ function ft_mediause($id, $ignore_perms = false){
  * @triggers SEARCH_QUERY_PAGELOOKUP
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @param string $id        page id
+ * @param bool   $in_ns     match against namespace as well?
+ * @param bool   $in_title  search in title?
+ * @return string[]
  */
 function ft_pageLookup($id, $in_ns=false, $in_title=false){
     $data = compact('id', 'in_ns', 'in_title');
@@ -213,6 +224,12 @@ function ft_pageLookup($id, $in_ns=false, $in_title=false){
     return trigger_event('SEARCH_QUERY_PAGELOOKUP', $data, '_ft_pageLookup');
 }
 
+/**
+ * Returns list of pages as array(pageid => First Heading)
+ *
+ * @param array &$data event data
+ * @return string[]
+ */
 function _ft_pageLookup(&$data){
     // split out original parameters
     $id = $data['id'];
@@ -270,6 +287,10 @@ function _ft_pageLookup(&$data){
  * Tiny helper function for comparing the searched title with the title
  * from the search index. This function is a wrapper around stripos with
  * adapted argument order and return value.
+ *
+ * @param string $search searched title
+ * @param string $title  title from index
+ * @return bool
  */
 function _ft_pageLookupTitleCompare($search, $title) {
     return stripos($title, $search) !== false;
@@ -279,6 +300,10 @@ function _ft_pageLookupTitleCompare($search, $title) {
  * Sort pages based on their namespace level first, then on their string
  * values. This makes higher hierarchy pages rank higher than lower hierarchy
  * pages.
+ *
+ * @param string $a
+ * @param string $b
+ * @return int Returns < 0 if $a is less than $b; > 0 if $a is greater than $b, and 0 if they are equal.
  */
 function ft_pagesorter($a, $b){
     $ac = count(explode(':',$a));
@@ -296,6 +321,10 @@ function ft_pagesorter($a, $b){
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @triggers FULLTEXT_SNIPPET_CREATE
+ *
+ * @param string $id page id
+ * @param array $highlight
+ * @return mixed
  */
 function ft_snippet($id,$highlight){
     $text = rawWiki($id);
@@ -390,6 +419,9 @@ function ft_snippet($id,$highlight){
 
 /**
  * Wraps a search term in regex boundary checks.
+ *
+ * @param string $term
+ * @return string
  */
 function ft_snippet_re_preprocess($term) {
     // do not process asian terms where word boundaries are not explicit
@@ -433,6 +465,7 @@ function ft_snippet_re_preprocess($term) {
  * based upon PEAR's PHP_Compat function for array_intersect_key()
  *
  * @param array $args An array of page arrays
+ * @return array
  */
 function ft_resultCombine($args){
     $array_count = count($args);
@@ -462,6 +495,8 @@ function ft_resultCombine($args){
  * based upon ft_resultCombine() function
  *
  * @param array $args An array of page arrays
+ * @return array
+ *
  * @author Kazutaka Miyasaka <kazmiya@gmail.com>
  */
 function ft_resultUnite($args) {
@@ -485,6 +520,8 @@ function ft_resultUnite($args) {
  * nearly identical to PHP5's array_diff_key()
  *
  * @param array $args An array of page arrays
+ * @return array
+ *
  * @author Kazutaka Miyasaka <kazmiya@gmail.com>
  */
 function ft_resultComplement($args) {
@@ -507,6 +544,10 @@ function ft_resultComplement($args) {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Kazutaka Miyasaka <kazmiya@gmail.com>
+ *
+ * @param Doku_Indexer $Indexer
+ * @param string $query search query
+ * @return array of search formulas
  */
 function ft_queryParser($Indexer, $query){
     /**
@@ -737,6 +778,12 @@ function ft_queryParser($Indexer, $query){
  * This function is used in ft_queryParser() and not for general purpose use.
  *
  * @author Kazutaka Miyasaka <kazmiya@gmail.com>
+ *
+ * @param Doku_Indexer $Indexer
+ * @param string       $term
+ * @param bool         $consider_asian
+ * @param bool         $phrase_mode
+ * @return string
  */
 function ft_termParser($Indexer, $term, $consider_asian = true, $phrase_mode = false) {
     $parsed = '';
diff --git a/inc/html.php b/inc/html.php
index ce6360175..adcd212ed 100644
--- a/inc/html.php
+++ b/inc/html.php
@@ -83,6 +83,10 @@ function html_denied() {
  * inserts section edit buttons if wanted or removes the markers
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $text
+ * @param bool   $show show section edit buttons?
+ * @return string
  */
 function html_secedit($text,$show=true){
     global $INFO;
@@ -101,8 +105,11 @@ function html_secedit($text,$show=true){
  * prepares section edit button data for event triggering
  * used as a callback in html_secedit
  *
- * @triggers HTML_SECEDIT_BUTTON
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $matches matches with regexp
+ * @return string
+ * @triggers HTML_SECEDIT_BUTTON
  */
 function html_secedit_button($matches){
     $data = array('secid'  => $matches[1],
@@ -121,6 +128,9 @@ function html_secedit_button($matches){
  * used as default action form HTML_SECEDIT_BUTTON
  *
  * @author Adrian Lang <lang@cosmocode.de>
+ *
+ * @param array $data name, section id and target
+ * @return string html
  */
 function html_secedit_get_button($data) {
     global $ID;
@@ -147,6 +157,8 @@ function html_secedit_get_button($data) {
  * Just the back to top button (in its own form)
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return string html
  */
 function html_topbtn(){
     global $lang;
@@ -161,6 +173,15 @@ function html_topbtn(){
  * If tooltip exists, the access key tooltip is replaced.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string         $name
+ * @param string         $id
+ * @param string         $akey   access key
+ * @param string[string] $params key-value pairs added as hidden inputs
+ * @param string         $method
+ * @param string         $tooltip
+ * @param bool|string    $label  label text, false: lookup btn_$name in localization
+ * @return string
  */
 function html_btn($name,$id,$akey,$params,$method='get',$tooltip='',$label=false){
     global $conf;
@@ -213,9 +234,11 @@ function html_btn($name,$id,$akey,$params,$method='get',$tooltip='',$label=false
 }
 
 /**
- * show a wiki page
+ * Show a wiki page
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param null|string $txt wiki text or null for showing $ID
  */
 function html_show($txt=null){
     global $ID;
@@ -281,6 +304,10 @@ function html_draft(){
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Harry Fuecks <hfuecks@gmail.com>
+ *
+ * @param string $html
+ * @param array|string $phrases
+ * @return string html
  */
 function html_hilight($html,$phrases){
     $phrases = (array) $phrases;
@@ -299,6 +326,9 @@ function html_hilight($html,$phrases){
  * Callback used by html_hilight()
  *
  * @author Harry Fuecks <hfuecks@gmail.com>
+ *
+ * @param array $m matches
+ * @return string html
  */
 function html_hilight_callback($m) {
     $hlight = unslash($m[0]);
@@ -646,6 +676,9 @@ function html_revisions($first=0, $media_id = false){
  * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
  * @author Ben Coburn <btcoburn@silicodon.net>
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param int $first
+ * @param string $show_changes
  */
 function html_recent($first=0, $show_changes='both'){
     global $conf;
@@ -833,6 +866,8 @@ function html_recent($first=0, $show_changes='both'){
  * Display page index
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $ns
  */
 function html_index($ns){
     global $conf;
@@ -861,6 +896,9 @@ function html_index($ns){
  * User function for html_buildlist()
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $item
+ * @return string
  */
 function html_list_index($item){
     global $ID, $conf;
@@ -891,6 +929,9 @@ function html_list_index($item){
  * it gives different classes to opened or closed "folders"
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $item
+ * @return string html
  */
 function html_li_index($item){
     if($item['type'] == "f"){
@@ -906,6 +947,9 @@ function html_li_index($item){
  * Default List item
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $item
+ * @return string html
  */
 function html_li_default($item){
     return '<li class="level'.$item['level'].'">';
@@ -1021,12 +1065,13 @@ function html_backlinks(){
 
 /**
  * Get header of diff HTML
+ *
  * @param string $l_rev   Left revisions
  * @param string $r_rev   Right revision
  * @param string $id      Page id, if null $ID is used
  * @param bool   $media   If it is for media files
  * @param bool   $inline  Return the header on a single line
- * @return array HTML snippets for diff header
+ * @return string[] HTML snippets for diff header
  */
 function html_diff_head($l_rev, $r_rev, $id = null, $media = false, $inline = false) {
     global $lang;
@@ -1482,7 +1527,7 @@ function html_diff_navigationlink($difftype, $linktype, $lrev, $rrev = null) {
 /**
  * Insert soft breaks in diff html
  *
- * @param $diffhtml
+ * @param string $diffhtml
  * @return string
  */
 function html_insert_softbreaks($diffhtml) {
@@ -1521,6 +1566,9 @@ REGEX;
  * show warning on conflict detection
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $text
+ * @param string $summary
  */
 function html_conflict($text,$summary){
     global $ID;
@@ -1681,7 +1729,6 @@ function html_edit(){
     global $lang;
     global $conf;
     global $TEXT;
-    global $RANGE;
 
     if ($INPUT->has('changecheck')) {
         $check = $INPUT->str('changecheck');
@@ -1783,6 +1830,7 @@ function html_edit(){
  * Display the default edit form
  *
  * Is the default action for HTML_EDIT_FORMSELECTION.
+ *
  * @param mixed[] $param
  */
 function html_edit_form($param) {
@@ -1802,6 +1850,8 @@ function html_edit_form($param) {
  * Adds a checkbox for minor edits for logged in users
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return array|bool
  */
 function html_minoredit(){
     global $conf;
@@ -2081,6 +2131,9 @@ function html_resendpwd() {
  * Return the TOC rendered to XHTML
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $toc
+ * @return string html
  */
 function html_TOC($toc){
     if(!count($toc)) return '';
@@ -2099,6 +2152,9 @@ function html_TOC($toc){
 
 /**
  * Callback for html_buildlist
+ *
+ * @param array $item
+ * @return string html
  */
 function html_list_toc($item){
     if(isset($item['hid'])){
@@ -2133,6 +2189,7 @@ function html_mktocitem($link, $text, $level, $hash='#'){
  * Triggers an event with the form name: HTML_{$name}FORM_OUTPUT
  *
  * @author Tom N Harris <tnharris@whoopdedo.org>
+ *
  * @param string     $name The name of the form
  * @param Doku_Form  $form The form
  */
@@ -2145,6 +2202,7 @@ function html_form($name, &$form) {
 /**
  * Form print function.
  * Just calls printForm() on the data object.
+ *
  * @param Doku_Form $data The form
  */
 function html_form_output($data) {
diff --git a/inc/httputils.php b/inc/httputils.php
index efeb2a56c..ac79aa176 100644
--- a/inc/httputils.php
+++ b/inc/httputils.php
@@ -15,6 +15,7 @@ define('HTTP_CHUNK_SIZE',16*1024);
  *
  * @author   Simon Willison <swillison@gmail.com>
  * @link     http://simonwillison.net/2003/Apr/23/conditionalGet/
+ *
  * @param    int $timestamp lastmodified time of the cache file
  * @returns  void or exits with previously header() commands executed
  */
@@ -64,6 +65,7 @@ function http_conditionalRequest($timestamp){
  * Let the webserver send the given file via x-sendfile method
  *
  * @author Chris Smith <chris@jalakai.co.uk>
+ *
  * @param string $file absolute path of file to send
  * @returns  void or exits with previous header() commands executed
  */
@@ -190,6 +192,9 @@ function http_rangeRequest($fh,$size,$mime){
  * (samepath/samefilename.sameext.gz) created after the uncompressed file
  *
  * @author Chris Smith <chris.eureka@jalakai.co.uk>
+ *
+ * @param string $uncompressed_file
+ * @return bool
  */
 function http_gzip_valid($uncompressed_file) {
     $gzip = $uncompressed_file.'.gz';
@@ -206,6 +211,9 @@ function http_gzip_valid($uncompressed_file) {
  * This function handles output of cacheable resource files. It ses the needed
  * HTTP headers. If a useable cache is present, it is passed to the web server
  * and the script is terminated.
+ *
+ * @param string $cache cache file name
+ * @param bool   $cache_ok    if cache can be used
  */
 function http_cached($cache, $cache_ok) {
     global $conf;
@@ -235,6 +243,9 @@ function http_cached($cache, $cache_ok) {
 
 /**
  * Cache content and print it
+ *
+ * @param string $file file name
+ * @param string $content
  */
 function http_cached_finish($file, $content) {
     global $conf;
diff --git a/inc/indexer.php b/inc/indexer.php
index 5ca2f0bb1..ec0c523e0 100644
--- a/inc/indexer.php
+++ b/inc/indexer.php
@@ -61,6 +61,8 @@ define('IDX_ASIAN', '(?:'.IDX_ASIAN1.'|'.IDX_ASIAN2.'|'.IDX_ASIAN3.')');
  *
  * @author Tom N Harris <tnharris@whoopdedo.org>
  * @author Michael Hamann <michael@content-space.de>
+ *
+ * @return int|string
  */
 function idx_get_version(){
     static $indexer_version = null;
@@ -84,6 +86,9 @@ function idx_get_version(){
  * Differs from strlen in handling of asian characters.
  *
  * @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string $w
+ * @return int
  */
 function wordlen($w){
     $l = strlen($w);
@@ -115,7 +120,8 @@ class Doku_Indexer {
      *
      * @param string    $page   a page name
      * @param string    $text   the body of the page
-     * @return boolean          the function completed successfully
+     * @return string|boolean  the function completed successfully
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author Andreas Gohr <andi@splitbrain.org>
      */
@@ -190,6 +196,7 @@ class Doku_Indexer {
      *
      * @param string    $text   content of the page
      * @return array            list of word IDs and number of times used
+     *
      * @author Andreas Gohr <andi@splitbrain.org>
      * @author Christopher Smith <chris@jalakai.co.uk>
      * @author Tom N Harris <tnharris@whoopdedo.org>
@@ -245,7 +252,8 @@ class Doku_Indexer {
      * @param string    $page   a page name
      * @param mixed     $key    a key string or array of key=>value pairs
      * @param mixed     $value  the value or list of values
-     * @return boolean          the function completed successfully
+     * @return boolean|string     the function completed successfully
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author Michael Hamann <michael@content-space.de>
      */
@@ -453,7 +461,8 @@ class Doku_Indexer {
      * Erases entries in all known indexes.
      *
      * @param string    $page   a page name
-     * @return boolean          the function completed successfully
+     * @return string|boolean  the function completed successfully
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     public function deletePage($page) {
@@ -474,6 +483,7 @@ class Doku_Indexer {
      *
      * @param string    $page   a page name
      * @return boolean          the function completed successfully
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function deletePageNoLock($page) {
@@ -568,6 +578,7 @@ class Doku_Indexer {
      * @param string    $text   plain text
      * @param boolean   $wc     are wildcards allowed?
      * @return array            list of words in the text
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author Andreas Gohr <andi@splitbrain.org>
      */
@@ -676,6 +687,7 @@ class Doku_Indexer {
      *
      * @param array  $tokens list of words to search for
      * @return array         list of page names with usage counts
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author Andreas Gohr <andi@splitbrain.org>
      */
@@ -730,6 +742,7 @@ class Doku_Indexer {
      * @param string    $value  search term to look for, must be a string or array of strings
      * @param callback  $func   comparison function
      * @return array            lists with page names, keys are query values if $value is array
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author Michael Hamann <michael@content-space.de>
      */
@@ -829,6 +842,7 @@ class Doku_Indexer {
      * @param array  $words  The query terms.
      * @param array  $result Set to word => array("length*id" ...)
      * @return array         Set to length => array(id ...)
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function getIndexWords(&$words, &$result) {
@@ -909,6 +923,7 @@ class Doku_Indexer {
      *
      * @param string    $key    list only pages containing the metadata key (optional)
      * @return array            list of page names
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     public function getPages($key=null) {
@@ -942,6 +957,7 @@ class Doku_Indexer {
      * @param int       $minlen minimum length of words to count
      * @param string    $key    metadata key to list. Uses the fulltext index if not given
      * @return array            list of words as the keys and frequency as values
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     public function histogram($min=1, $max=0, $minlen=3, $key=null) {
@@ -1002,6 +1018,8 @@ class Doku_Indexer {
      * Lock the indexer.
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
+     *
+     * @return bool|string
      */
     protected function lock() {
         global $conf;
@@ -1033,6 +1051,8 @@ class Doku_Indexer {
      * Release the indexer lock.
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
+     *
+     * @return bool
      */
     protected function unlock() {
         global $conf;
@@ -1050,6 +1070,7 @@ class Doku_Indexer {
      * @param string    $idx    name of the index
      * @param string    $suffix subpart identifier
      * @return array            list of lines without CR or LF
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function getIndex($idx, $suffix) {
@@ -1066,6 +1087,7 @@ class Doku_Indexer {
      * @param string    $suffix subpart identifier
      * @param array     $lines  list of lines without LF
      * @return bool             If saving succeeded
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function saveIndex($idx, $suffix, &$lines) {
@@ -1090,6 +1112,7 @@ class Doku_Indexer {
      * @param string    $suffix subpart identifier
      * @param int       $id     the line number
      * @return string           a line with trailing whitespace removed
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function getIndexKey($idx, $suffix, $id) {
@@ -1114,6 +1137,7 @@ class Doku_Indexer {
      * @param int       $id     the line number
      * @param string    $line   line to write
      * @return bool             If saving succeeded
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function saveIndexKey($idx, $suffix, $id, $line) {
@@ -1155,6 +1179,7 @@ class Doku_Indexer {
      * @param string    $suffix subpart identifier
      * @param string    $value  line to find in the index
      * @return int|bool          line number of the value in the index or false if writing the index failed
+     *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      */
     protected function addIndexKey($idx, $suffix, $value) {
@@ -1178,6 +1203,8 @@ class Doku_Indexer {
      * a sorted array of lengths of the words used in the wiki.
      *
      * @author YoBoY <yoboy.leguesh@gmail.com>
+     *
+     * @return array
      */
     protected function listIndexLengths() {
         return idx_listIndexLengths();
@@ -1190,6 +1217,9 @@ class Doku_Indexer {
      * that there are indices for.
      *
      * @author YoBoY <yoboy.leguesh@gmail.com>
+     *
+     * @param array|int $filter
+     * @return array
      */
     protected function indexLengths($filter) {
         global $conf;
@@ -1216,6 +1246,11 @@ class Doku_Indexer {
      * Insert or replace a tuple in a line.
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
+     *
+     * @param string $line
+     * @param string $id
+     * @param int    $count
+     * @return string
      */
     protected function updateTuple($line, $id, $count) {
         if ($line != ''){
@@ -1237,6 +1272,10 @@ class Doku_Indexer {
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param array $keys
+     * @param string $line
+     * @return array
      */
     protected function parseTuples(&$keys, $line) {
         $result = array();
@@ -1257,13 +1296,16 @@ class Doku_Indexer {
      * Sum the counts in a list of tuples.
      *
      * @author Tom N Harris <tnharris@whoopdedo.org>
+     *
+     * @param string $line
+     * @return int
      */
     protected function countTuples($line) {
         $freq = 0;
         $parts = explode(':', $line);
         foreach ($parts as $tuple) {
             if ($tuple === '') continue;
-            list($pid, $cnt) = explode('*', $tuple);
+            list(/* $pid */, $cnt) = explode('*', $tuple);
             $freq += (int)$cnt;
         }
         return $freq;
@@ -1273,7 +1315,8 @@ class Doku_Indexer {
 /**
  * Create an instance of the indexer.
  *
- * @return Doku_Indexer               a Doku_Indexer
+ * @return Doku_Indexer    a Doku_Indexer
+ *
  * @author Tom N Harris <tnharris@whoopdedo.org>
  */
 function idx_get_indexer() {
@@ -1288,6 +1331,7 @@ function idx_get_indexer() {
  * Returns words that will be ignored.
  *
  * @return array                list of stop words
+ *
  * @author Tom N Harris <tnharris@whoopdedo.org>
  */
 function & idx_get_stopwords() {
@@ -1312,7 +1356,8 @@ function & idx_get_stopwords() {
  * @param string        $page   name of the page to index
  * @param boolean       $verbose    print status messages
  * @param boolean       $force  force reindexing even when the index is up to date
- * @return boolean              the function completed successfully
+ * @return string|boolean  the function completed successfully
+ *
  * @author Tom N Harris <tnharris@whoopdedo.org>
  */
 function idx_addPage($page, $verbose=false, $force=false) {
@@ -1441,6 +1486,10 @@ function idx_tokenizer($string, $wc=false) {
  * Read the list of words in an index (if it exists).
  *
  * @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string $idx
+ * @param string $suffix
+ * @return array
  */
 function idx_getIndex($idx, $suffix) {
     global $conf;
@@ -1456,6 +1505,8 @@ function idx_getIndex($idx, $suffix) {
  * a sorted array of lengths of the words used in the wiki.
  *
  * @author YoBoY <yoboy.leguesh@gmail.com>
+ *
+ * @return array
  */
 function idx_listIndexLengths() {
     global $conf;
@@ -1510,6 +1561,9 @@ function idx_listIndexLengths() {
  * that there are indices for.
  *
  * @author YoBoY <yoboy.leguesh@gmail.com>
+ *
+ * @param array|int $filter
+ * @return array
  */
 function idx_indexLengths($filter) {
     global $conf;
@@ -1539,6 +1593,9 @@ function idx_indexLengths($filter) {
  * not a letter, number, or underscore.
  *
  * @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string $name
+ * @return string
  */
 function idx_cleanName($name) {
     $name = utf8_romanize(trim((string)$name));
diff --git a/inc/io.php b/inc/io.php
index 27a34b045..bfa394a17 100644
--- a/inc/io.php
+++ b/inc/io.php
@@ -20,6 +20,7 @@ if(!defined('DOKU_INC')) die('meh.');
  * @param string $id      - a pageid, the namespace of that id will be tried to deleted
  * @param string $basedir - the config name of the type to delete (datadir or mediadir usally)
  * @return bool - true if at least one namespace was deleted
+ *
  * @author  Andreas Gohr <andi@splitbrain.org>
  * @author Ben Coburn <btcoburn@silicodon.net>
  */
@@ -60,6 +61,11 @@ function io_sweepNS($id,$basedir='datadir'){
  * $data[3]    rev: The page revision, false for current wiki pages.
  *
  * @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string   $file filename
+ * @param string   $id page id
+ * @param bool|int $rev revision timestamp
+ * @return string
  */
 function io_readWikiPage($file, $id, $rev=false) {
     if (empty($rev)) { $rev = false; }
@@ -69,7 +75,11 @@ function io_readWikiPage($file, $id, $rev=false) {
 
 /**
  * Callback adapter for io_readFile().
+ *
  * @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param array $data event data
+ * @return string
  */
 function _io_readWikiPage_action($data) {
     if (is_array($data) && is_array($data[0]) && count($data[0])===2) {
@@ -88,6 +98,10 @@ function _io_readWikiPage_action($data) {
  * be sure to set $clean to false!
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file  filename
+ * @param bool   $clean
+ * @return string
  */
 function io_readFile($file,$clean=true){
     $ret = '';
@@ -108,9 +122,12 @@ function io_readFile($file,$clean=true){
 }
 /**
  * Returns the content of a .bz2 compressed file as string
+ *
  * @author marcel senf <marcel@rucksackreinigung.de>
+ *
+ * @param string $file filename
+ * @return string content
  */
-
 function bzfile($file){
     $bz = bzopen($file,"r");
     $str = '';
@@ -138,6 +155,12 @@ function bzfile($file){
  * $data[3]    rev: The page revision, false for current wiki pages.
  *
  * @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string $file      filename
+ * @param string $content
+ * @param string $id        page id
+ * @param int|bool $rev timestamp of revision
+ * @return bool
  */
 function io_writeWikiPage($file, $content, $id, $rev=false) {
     if (empty($rev)) { $rev = false; }
@@ -149,6 +172,9 @@ function io_writeWikiPage($file, $content, $id, $rev=false) {
 /**
  * Callback adapter for io_saveFile().
  * @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param array $data event data
+ * @return bool
  */
 function _io_writeWikiPage_action($data) {
     if (is_array($data) && is_array($data[0]) && count($data[0])===3) {
@@ -168,7 +194,11 @@ function _io_writeWikiPage_action($data) {
  * and bz2 if extension is .bz2
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
- * @return bool true on success
+ *
+ * @param string $file filename path to file
+ * @param string $content
+ * @param bool   $append
+ * @return bool true on success, otherwise false
  */
 function io_saveFile($file,$content,$append=false){
     global $conf;
@@ -221,6 +251,10 @@ function io_saveFile($file,$content,$append=false){
  * 2005-10-14 : added regex option -- Christopher Smith <chris@jalakai.co.uk>
  *
  * @author Steven Danz <steven-danz@kc.rr.com>
+ *
+ * @param string $file    filename
+ * @param string $badline exact linematch to remove
+ * @param bool   $regex   use regexp?
  * @return bool true on success
  */
 function io_deleteFromFile($file,$badline,$regex=false){
@@ -285,6 +319,8 @@ function io_deleteFromFile($file,$badline,$regex=false){
  * the lock is assumed to be stale and the function goes on
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file filename
  */
 function io_lock($file){
     global $conf;
@@ -311,6 +347,8 @@ function io_lock($file){
  * Unlocks a file
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file filename
  */
 function io_unlock($file){
     global $conf;
@@ -331,6 +369,9 @@ function io_unlock($file){
  * $data[1]    ns_type: 'pages' or 'media' namespace tree.
  *
  * @author Ben Coburn <btcoburn@silicodon.net>
+ *
+ * @param string $id page id
+ * @param string $ns_type 'pages' or 'media'
  */
 function io_createNamespace($id, $ns_type='pages') {
     // verify ns_type
@@ -365,6 +406,8 @@ function io_createNamespace($id, $ns_type='pages') {
  * Create the directory needed for the given file
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file file name
  */
 function io_makeFileDir($file){
     $dir = dirname($file);
@@ -379,6 +422,9 @@ function io_makeFileDir($file){
  * @link    http://www.php.net/manual/en/function.mkdir.php
  * @author  <saint@corenova.com>
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $target filename
+ * @return bool|int|string
  */
 function io_mkdir_p($target){
     global $conf;
@@ -454,6 +500,9 @@ function io_rmdir($path, $removefiles = false) {
  * This is used when the safemode workaround is enabled
  *
  * @author <andi@splitbrain.org>
+ *
+ * @param string $dir name of the new directory
+ * @return false|string
  */
 function io_mkdir_ftp($dir){
     global $conf;
@@ -488,6 +537,8 @@ function io_mkdir_ftp($dir){
  * its path.
  *
  * @author Michael Klier <chi@chimeric.de>
+ *
+ * @return false|string path to new directory or false
  */
 function io_mktmpdir() {
     global $conf;
@@ -516,6 +567,13 @@ function io_mktmpdir() {
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param string $url           url to download
+ * @param string $file          path to file or directory where to save
+ * @param bool   $useAttachment if true: try to use name of download, uses otherwise $defaultName, false: uses $file as path to file
+ * @param string $defaultName   fallback for if using $useAttachment
+ * @param int    $maxSize       maximum file size
+ * @return bool|string          if failed false, otherwise true or the name of the file in the given dir
  */
 function io_download($url,$file,$useAttachment=false,$defaultName='',$maxSize=2097152){
     global $conf;
@@ -563,6 +621,10 @@ function io_download($url,$file,$useAttachment=false,$defaultName='',$maxSize=20
  *
  * rename() can not overwrite existing files on Windows
  * this function will use copy/unlink instead
+ *
+ * @param string $from
+ * @param string $to
+ * @return bool succes or fail
  */
 function io_rename($from,$to){
     global $conf;
@@ -582,6 +644,11 @@ function io_rename($from,$to){
  * Returns the exit code from the process.
  *
  * @author Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string $cmd
+ * @param string $input  input pipe
+ * @param string $output output pipe
+ * @return int exit code from process
  */
 function io_exec($cmd, $input, &$output){
     $descspec = array(
diff --git a/inc/media.php b/inc/media.php
index 7770d3cc9..4ad67369d 100644
--- a/inc/media.php
+++ b/inc/media.php
@@ -16,6 +16,9 @@ if(!defined('NL')) define('NL',"\n");
  * their CSS tags except pagenames won't be links.
  *
  * @author Matthias Grimm <matthiasgrimm@users.sourceforge.net>
+ *
+ * @param array $data
+ * @param string $id
  */
 function media_filesinuse($data,$id){
     global $lang;
@@ -45,7 +48,7 @@ function media_filesinuse($data,$id){
  * @param string $id media id
  * @param int $auth permission level
  * @param array $data
- * @return bool
+ * @return false|string
  */
 function media_metasave($id,$auth,$data){
     if($auth < AUTH_UPLOAD) return false;
@@ -91,6 +94,7 @@ function media_metasave($id,$auth,$data){
  * check if a media is external source
  *
  * @author Gerrit Uitslag <klapinklapin@gmail.com>
+ *
  * @param string $id the media ID or URL
  * @return bool
  */
@@ -103,6 +107,7 @@ function media_isexternal($id){
  * Check if a media item is public (eg, external URL or readable by @ALL)
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $id  the media ID or URL
  * @return bool
  */
@@ -214,6 +219,7 @@ define('DOKU_MEDIA_EMPTY_NS', 8);
  * If configured, checks for media references before deletion
  *
  * @author             Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $id media id
  * @param int $auth no longer used
  * @return int One of: 0,
@@ -266,9 +272,9 @@ function media_delete($id,$auth){
 /**
  * Handle file uploads via XMLHttpRequest
  *
- * @param string $ns target namespace
- * @param int $auth current auth check result
- * @return mixed false on error, id of the new file on success
+ * @param string $ns   target namespace
+ * @param int    $auth current auth check result
+ * @return false|string false on error, id of the new file on success
  */
 function media_upload_xhr($ns,$auth){
     if(!checkSecurityToken()) return false;
@@ -311,10 +317,11 @@ function media_upload_xhr($ns,$auth){
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Michael Klier <chi@chimeric.de>
- * @param string $ns target namespace
- * @param int $auth current auth check result
- * @param bool|array $file $_FILES member, $_FILES['upload'] if false
- * @return mixed false on error, id of the new file on success
+ *
+ * @param string     $ns    target namespace
+ * @param int        $auth  current auth check result
+ * @param bool|array $file  $_FILES member, $_FILES['upload'] if false
+ * @return false|string false on error, id of the new file on success
  */
 function media_upload($ns,$auth,$file=false){
     if(!checkSecurityToken()) return false;
@@ -358,6 +365,7 @@ function media_upload($ns,$auth,$file=false){
  * Using copy, makes sure any setgid bits on the media directory are honored
  *
  * @see   move_uploaded_file()
+ *
  * @param string $from
  * @param string $to
  * @return bool
@@ -383,14 +391,13 @@ function copy_uploaded_file($from, $to){
  * $data[5]     move:
  *
  * @triggers MEDIA_UPLOAD_FINISH
- */
-/**
- * @param array $file
+ *
+ * @param array  $file
  * @param string $id
- * @param bool $ow
- * @param int $auth permission level
+ * @param bool   $ow   overwrite?
+ * @param int    $auth permission level
  * @param string $move function name
- * @return array|mixed
+ * @return false|array|string
  */
 function media_save($file, $id, $ow, $auth, $move) {
     if($auth < AUTH_UPLOAD) {
@@ -453,8 +460,12 @@ function media_save($file, $id, $ow, $auth, $move) {
 }
 
 /**
- * Callback adapter for media_upload_finish()
+ * Callback adapter for media_upload_finish() triggered by MEDIA_UPLOAD_FINISH
+ *
  * @author Michael Klier <chi@chimeric.de>
+ *
+ * @param array $data event data
+ * @return false|array|string
  */
 function _media_upload_action($data) {
     // fixme do further sanity tests of given data?
@@ -471,6 +482,14 @@ function _media_upload_action($data) {
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Michael Klier <chi@chimeric.de>
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string $fn_tmp
+ * @param string $fn
+ * @param string $id        media id
+ * @param string $imime     mime type
+ * @param bool   $overwrite overwrite existing?
+ * @param string $move      function name
+ * @return array|string
  */
 function media_upload_finish($fn_tmp, $fn, $id, $imime, $overwrite, $move = 'move_uploaded_file') {
     global $conf;
@@ -514,6 +533,7 @@ function media_upload_finish($fn_tmp, $fn, $id, $imime, $overwrite, $move = 'mov
  * directory
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
  * @param string $id
  * @return int - revision date
  */
@@ -557,6 +577,10 @@ function media_saveOldRevision($id){
  * @author Andreas Gohr <andi@splitbrain.org>
  * @link   http://www.splitbrain.org/blog/2007-02/12-internet_explorer_facilitates_cross_site_scripting
  * @fixme  check all 26 magic IE filetypes here?
+ *
+ * @param string $file path to file
+ * @param string $mime mimetype
+ * @return int
  */
 function media_contentcheck($file,$mime){
     global $conf;
@@ -566,14 +590,14 @@ function media_contentcheck($file,$mime){
             $bytes = fread($fh, 256);
             fclose($fh);
             if(preg_match('/<(script|a|img|html|body|iframe)[\s>]/i',$bytes)){
-                return -3;
+                return -3; //XSS: possibly malicious content
             }
         }
     }
     if(substr($mime,0,6) == 'image/'){
         $info = @getimagesize($file);
         if($mime == 'image/gif' && $info[2] != 1){
-            return -1;
+            return -1; // uploaded content did not match the file extension
         }elseif($mime == 'image/jpeg' && $info[2] != 2){
             return -1;
         }elseif($mime == 'image/png' && $info[2] != 3){
@@ -584,7 +608,7 @@ function media_contentcheck($file,$mime){
         global $TEXT;
         $TEXT = io_readFile($file);
         if(checkwordblock()){
-            return -2;
+            return -2; //blocked by the spam blacklist
         }
     }
     return 0;
@@ -594,6 +618,12 @@ function media_contentcheck($file,$mime){
  * Send a notify mail on uploads
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string   $id      media id
+ * @param string   $file    path to file
+ * @param string   $mime    mime type
+ * @param bool|int $old_rev revision timestamp or false
+ * @return bool
  */
 function media_notify($id,$file,$mime,$old_rev=false){
     global $conf;
@@ -605,6 +635,12 @@ function media_notify($id,$file,$mime,$old_rev=false){
 
 /**
  * List all files in a given Media namespace
+ *
+ * @param string      $ns
+ * @param null|int    $auth           permission level
+ * @param string      $jump           id
+ * @param bool        $fullscreenview
+ * @param bool|string $sort           sorting order
  */
 function media_filelist($ns,$auth=null,$jump='',$fullscreenview=false,$sort=false){
     global $conf;
@@ -747,6 +783,7 @@ function media_tab_files_options(){
  * Returns type of sorting for the list of files in media manager
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
  * @return string - sort type
  */
 function _media_get_sort_type() {
@@ -757,6 +794,7 @@ function _media_get_sort_type() {
  * Returns type of listing for the list of files in media manager
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
  * @return string - list type
  */
 function _media_get_list_type() {
@@ -788,6 +826,10 @@ function _media_get_display_param($param, $values) {
  * Prints tab that displays a list of all files
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string    $ns
+ * @param null|int  $auth permission level
+ * @param string    $jump item id
  */
 function media_tab_files($ns,$auth=null,$jump='') {
     global $lang;
@@ -804,6 +846,10 @@ function media_tab_files($ns,$auth=null,$jump='') {
  * Prints tab that displays uploading form
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string   $ns
+ * @param null|int $auth permission level
+ * @param string   $jump item id
  */
 function media_tab_upload($ns,$auth=null,$jump='') {
     global $lang;
@@ -821,6 +867,9 @@ function media_tab_upload($ns,$auth=null,$jump='') {
  * Prints tab that displays search form
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
+ * @param string $ns
+ * @param null|int $auth permission level
  */
 function media_tab_search($ns,$auth=null) {
     global $INPUT;
@@ -843,8 +892,8 @@ function media_tab_search($ns,$auth=null) {
  *
  * @param string     $image media id
  * @param string     $ns
- * @param null|int   $auth permission level
- * @param string|int $rev
+ * @param null|int   $auth  permission level
+ * @param string|int $rev   revision timestamp or empty string
  */
 function media_tab_view($image, $ns, $auth=null, $rev='') {
     global $lang;
@@ -910,10 +959,11 @@ function media_tab_history($image, $ns, $auth=null) {
 /**
  * Prints mediafile details
  *
- * @param string        $image media id
- * @param int           $auth permission level
- * @param int|string    $rev revision timestamp or empty string
- * @param JpegMeta|bool $meta
+ * @param string         $image media id
+ * @param int            $auth permission level
+ * @param int|string     $rev revision timestamp or empty string
+ * @param JpegMeta|bool  $meta
+ *
  * @author Kate Arzamastseva <pshns@ukr.net>
  */
 function media_preview($image, $auth, $rev='', $meta=false) {
@@ -950,8 +1000,8 @@ function media_preview($image, $auth, $rev='', $meta=false) {
  * @author Kate Arzamastseva <pshns@ukr.net>
  *
  * @param string     $image media id
- * @param int        $auth permission level
- * @param string|int $rev revision timestamp, or empty string
+ * @param int        $auth  permission level
+ * @param string|int $rev   revision timestamp, or empty string
  */
 function media_preview_buttons($image, $auth, $rev='') {
     global $lang, $conf;
@@ -1003,9 +1053,9 @@ function media_preview_buttons($image, $auth, $rev='') {
  * @author Kate Arzamastseva <pshns@ukr.net>
  * @param string         $image
  * @param int|string     $rev
- * @param JpegMeta|bool $meta
+ * @param JpegMeta|bool  $meta
  * @param int            $size
- * @return array|bool
+ * @return array|false
  */
 function media_image_preview_size($image, $rev, $meta, $size = 500) {
     if (!preg_match("/\.(jpe?g|gif|png)$/", $image) || !file_exists(mediaFN($image, $rev))) return false;
@@ -1027,9 +1077,9 @@ function media_image_preview_size($image, $rev, $meta, $size = 500) {
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
  *
- * @param array    $tags
+ * @param array    $tags array with tags, first existing is returned
  * @param JpegMeta $meta
- * @param string   $alt
+ * @param string   $alt  alternative value
  * @return string
  */
 function media_getTag($tags,$meta,$alt=''){
@@ -1045,7 +1095,7 @@ function media_getTag($tags,$meta,$alt=''){
  * @author Kate Arzamastseva <pshns@ukr.net>
  *
  * @param JpegMeta $meta
- * @return array
+ * @return array list of tags of the mediafile
  */
 function media_file_tags($meta) {
     // load the field descriptions
@@ -1074,8 +1124,7 @@ function media_file_tags($meta) {
  * Prints mediafile tags
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
- */
-/**
+ *
  * @param string        $image image id
  * @param int           $auth  permission level
  * @param string|int    $rev   revision timestamp, or empty string
@@ -1104,13 +1153,12 @@ function media_details($image, $auth, $rev='', $meta=false) {
  * Shows difference between two revisions of file
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
- */
-/**
+ *
  * @param string $image  image id
  * @param string $ns
  * @param int $auth permission level
  * @param bool $fromajax
- * @return void|bool|string
+ * @return false|null|string
  */
 function media_diff($image, $ns, $auth, $fromajax = false) {
     global $conf;
@@ -1170,14 +1218,13 @@ function media_diff($image, $ns, $auth, $fromajax = false) {
 
     // trigger event
     return trigger_event('MEDIA_DIFF', $data, '_media_file_diff', true);
-
 }
 
 /**
  * Callback for media file diff
  *
- * @param $data
- * @return bool|void
+ * @param array $data event data
+ * @return false|null
  */
 function _media_file_diff($data) {
     if(is_array($data) && count($data)===6) {
@@ -1318,11 +1365,12 @@ function media_file_diff($image, $l_rev, $r_rev, $ns, $auth, $fromajax){
  * and slider
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
- * @param string $image
- * @param int $l_rev revision timestamp, or empty string
- * @param int $r_rev revision timestamp, or empty string
- * @param array $l_size
- * @param array $r_size
+ *
+ * @param string $image   image id
+ * @param int    $l_rev   revision timestamp, or empty string
+ * @param int    $r_rev   revision timestamp, or empty string
+ * @param array  $l_size  array with width and height
+ * @param array  $r_size  array with width and height
  * @param string $type
  */
 function media_image_diff($image, $l_rev, $r_rev, $l_size, $r_size, $type) {
@@ -1355,10 +1403,11 @@ function media_image_diff($image, $l_rev, $r_rev, $l_size, $r_size, $type) {
 /**
  * Restores an old revision of a media file
  *
- * @param string $image
- * @param int $rev
- * @param int $auth
+ * @param string $image media id
+ * @param int    $rev   revision timestamp or empty string
+ * @param int    $auth
  * @return string - file's id
+ *
  * @author Kate Arzamastseva <pshns@ukr.net>
  */
 function media_restore($image, $rev, $auth){
@@ -1444,10 +1493,10 @@ function media_searchlist($query,$ns,$auth=null,$fullscreen=false,$sort='natural
 /**
  * Formats and prints one file in the list
  *
- * @param array $item
- * @param int $auth permission level
- * @param string $jump item id
- * @param bool $display_namespace
+ * @param array     $item
+ * @param int       $auth              permission level
+ * @param string    $jump              item id
+ * @param bool      $display_namespace
  */
 function media_printfile($item,$auth,$jump,$display_namespace=false){
     global $lang;
@@ -1524,9 +1573,9 @@ function media_printfile($item,$auth,$jump,$display_namespace=false){
 /**
  * Display a media icon
  *
- * @param $filename
- * @param string $size the size subfolder, if not specified 16x16 is used
- * @return string
+ * @param string $filename media id
+ * @param string $size     the size subfolder, if not specified 16x16 is used
+ * @return string html
  */
 function media_printicon($filename, $size=''){
     list($ext) = mimetype(mediaFN($filename),false);
@@ -1546,8 +1595,8 @@ function media_printicon($filename, $size=''){
  * @author Kate Arzamastseva <pshns@ukr.net>
  *
  * @param array       $item
- * @param int         $auth
- * @param bool|string $jump
+ * @param int         $auth              permission level
+ * @param bool|string $jump              item id
  * @param bool        $display_namespace
  */
 function media_printfile_thumbs($item,$auth,$jump=false,$display_namespace=false){
@@ -1598,7 +1647,7 @@ function media_printfile_thumbs($item,$auth,$jump=false,$display_namespace=false
  * Prints a thumbnail and metainfo
  *
  * @param array $item
- * @param bool $fullscreen
+ * @param bool  $fullscreen
  */
 function media_printimgdetail($item, $fullscreen=false){
     // prepare thumbnail
@@ -1662,15 +1711,15 @@ function media_printimgdetail($item, $fullscreen=false){
 }
 
 /**
- * Build link based on the current, adding/rewriting
- * parameters
+ * Build link based on the current, adding/rewriting parameters
  *
  * @author Kate Arzamastseva <pshns@ukr.net>
+ *
  * @param array|bool $params
- * @param string     $amp - separator
- * @param bool       $abs
- * @param bool       $params_array
- * @return string|array - link
+ * @param string     $amp           separator
+ * @param bool       $abs           absolute url?
+ * @param bool       $params_array  return the parmeters array?
+ * @return string|array - link or link parameters
  */
 function media_managerURL($params=false, $amp='&amp;', $abs=false, $params_array=false) {
     global $ID;
@@ -1703,8 +1752,8 @@ function media_managerURL($params=false, $amp='&amp;', $abs=false, $params_array
  * @author Kate Arzamastseva <pshns@ukr.net>
  *
  * @param string $ns
- * @param int $auth permission level
- * @param bool $fullscreen
+ * @param int    $auth permission level
+ * @param bool  $fullscreen
  */
 function media_uploadform($ns, $auth, $fullscreen = false){
     global $lang;
@@ -1873,6 +1922,9 @@ function media_nstree($ns){
  * Prints a media namespace tree item
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $item
+ * @return string html
  */
 function media_nstree_item($item){
     global $INPUT;
@@ -1896,6 +1948,9 @@ function media_nstree_item($item){
  * Prints a media namespace tree item opener
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $item
+ * @return string html
  */
 function media_nstree_li($item){
     $class='media level'.$item['level'];
@@ -1917,6 +1972,12 @@ function media_nstree_li($item){
  * Resizes the given image to the given size
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file filename, path to file
+ * @param string $ext  extension
+ * @param int    $w    desired width
+ * @param int    $h    desired height
+ * @return string path to resized or original size if failed
  */
 function media_resize_image($file, $ext, $w, $h=0){
     global $conf;
@@ -1937,9 +1998,10 @@ function media_resize_image($file, $ext, $w, $h=0){
     $local = getCacheName($file,'.media.'.$w.'x'.$h.'.'.$ext);
     $mtime = @filemtime($local); // 0 if not exists
 
-    if( $mtime > filemtime($file) ||
-            media_resize_imageIM($ext,$file,$info[0],$info[1],$local,$w,$h) ||
-            media_resize_imageGD($ext,$file,$info[0],$info[1],$local,$w,$h) ){
+    if($mtime > filemtime($file) ||
+        media_resize_imageIM($ext, $file, $info[0], $info[1], $local, $w, $h) ||
+        media_resize_imageGD($ext, $file, $info[0], $info[1], $local, $w, $h)
+    ) {
         if(!empty($conf['fperm'])) @chmod($local, $conf['fperm']);
         return $local;
     }
@@ -1955,6 +2017,12 @@ function media_resize_image($file, $ext, $w, $h=0){
  * image because most pics are more interesting in that area (rule of thirds)
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file filename, path to file
+ * @param string $ext  extension
+ * @param int    $w    desired width
+ * @param int    $h    desired height
+ * @return string path to resized or original size if failed
  */
 function media_crop_image($file, $ext, $w, $h=0){
     global $conf;
@@ -2019,7 +2087,7 @@ function media_crop_image($file, $ext, $w, $h=0){
  * @param string  $id    id of the image
  * @param int     $w     resize/crop width
  * @param int     $h     resize/crop height
- * @return string
+ * @return string token or empty string if no token required
  */
 function media_get_token($id,$w,$h){
     // token is only required for modified images
@@ -2042,6 +2110,11 @@ function media_get_token($id,$w,$h){
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
  * @author  Pavel Vitis <Pavel.Vitis@seznam.cz>
+ *
+ * @param string $url
+ * @param string $ext   extension
+ * @param int    $cache cachetime in seconds
+ * @return false|string path to cached file
  */
 function media_get_from_URL($url,$ext,$cache){
     global $conf;
@@ -2054,12 +2127,12 @@ function media_get_from_URL($url,$ext,$cache){
     $mtime = @filemtime($local); // 0 if not exists
 
     //decide if download needed:
-    if( ($mtime == 0) ||                           // cache does not exist
-            ($cache != -1 && $mtime < time()-$cache)   // 'recache' and cache has expired
-      ){
-        if(media_image_download($url,$local)){
+    if(($mtime == 0) || // cache does not exist
+        ($cache != -1 && $mtime < time() - $cache) // 'recache' and cache has expired
+    ) {
+        if(media_image_download($url, $local)) {
             return $local;
-        }else{
+        } else {
             return false;
         }
     }
@@ -2075,6 +2148,10 @@ function media_get_from_URL($url,$ext,$cache){
  * Download image files
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $url
+ * @param string $file path to file in which to put the downloaded content
+ * @return bool
  */
 function media_image_download($url,$file){
     global $conf;
@@ -2110,6 +2187,15 @@ function media_image_download($url,$file){
  *
  * @author Pavel Vitis <Pavel.Vitis@seznam.cz>
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $ext     extension
+ * @param string $from    filename path to file
+ * @param int    $from_w  original width
+ * @param int    $from_h  original height
+ * @param string $to      path to resized file
+ * @param int    $to_w    desired width
+ * @param int    $to_h    desired height
+ * @return bool
  */
 function media_resize_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h){
     global $conf;
@@ -2134,6 +2220,17 @@ function media_resize_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h){
  * crop images using external ImageMagick convert program
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $ext     extension
+ * @param string $from    filename path to file
+ * @param int    $from_w  original width
+ * @param int    $from_h  original height
+ * @param string $to      path to resized file
+ * @param int    $to_w    desired width
+ * @param int    $to_h    desired height
+ * @param int    $ofs_x   offset of crop centre
+ * @param int    $ofs_y   offset of crop centre
+ * @return bool
  */
 function media_crop_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x,$ofs_y){
     global $conf;
@@ -2159,6 +2256,17 @@ function media_crop_imageIM($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x,$o
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Sebastian Wienecke <s_wienecke@web.de>
+ *
+ * @param string $ext     extension
+ * @param string $from    filename path to file
+ * @param int    $from_w  original width
+ * @param int    $from_h  original height
+ * @param string $to      path to resized file
+ * @param int    $to_w    desired width
+ * @param int    $to_h    desired height
+ * @param int    $ofs_x   offset of crop centre
+ * @param int    $ofs_y   offset of crop centre
+ * @return bool
  */
 function media_resize_imageGD($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x=0,$ofs_y=0){
     global $conf;
@@ -2261,9 +2369,9 @@ function media_resize_imageGD($ext,$from,$from_w,$from_h,$to,$to_w,$to_h,$ofs_x=
  * Return other media files with the same base name
  * but different extensions.
  *
- * @param string $src       - ID of media file
- * @param array $exts       - alternative extensions to find other files for
- * @return array            - mime type => file ID
+ * @param string   $src     - ID of media file
+ * @param string[] $exts    - alternative extensions to find other files for
+ * @return array            - array(mime type => file ID)
  *
  * @author Anika Henke <anika@selfthinker.org>
  */
@@ -2288,7 +2396,7 @@ function media_alternativefiles($src, $exts){
  * Check if video/audio is supported to be embedded.
  *
  * @param string $mime      - mimetype of media file
- * @param string $type      - type of media files to check ('video', 'audio', or none)
+ * @param string $type      - type of media files to check ('video', 'audio', or null for all)
  * @return boolean
  *
  * @author Anika Henke <anika@selfthinker.org>
diff --git a/inc/pageutils.php b/inc/pageutils.php
index adfb10cc7..b9c6418e2 100644
--- a/inc/pageutils.php
+++ b/inc/pageutils.php
@@ -20,7 +20,7 @@
  *
  * @param string $param  the $_REQUEST variable name, default 'id'
  * @param bool   $clean  if true, ID is cleaned
- * @return mixed|string
+ * @return string
  */
 function getID($param='id',$clean=true){
     /** @var Input $INPUT */
@@ -97,6 +97,7 @@ function getID($param='id',$clean=true){
  * converted to unaccented ones
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param  string  $raw_id    The pageid to clean
  * @param  boolean $ascii     Force ASCII
  * @return string cleaned id
@@ -152,7 +153,7 @@ function cleanID($raw_id,$ascii=false){
  * @author Andreas Gohr <andi@splitbrain.org>
  *
  * @param string $id
- * @return string|bool the namespace part or false if the given ID has no namespace (root)
+ * @return string|false the namespace part or false if the given ID has no namespace (root)
  */
 function getNS($id){
     $pos = strrpos((string)$id,':');
@@ -435,7 +436,7 @@ function localeFN($id,$ext='txt'){
  * @param string $ns     namespace which is context of id
  * @param string $id     relative id
  * @param bool   $clean  flag indicating that id should be cleaned
- * @return mixed|string
+ * @return string
  */
 function resolve_id($ns,$id,$clean=true){
     global $conf;
@@ -718,6 +719,7 @@ function utf8_decodeFN($file){
  * Used for sidebars, but can be used other stuff as well
  *
  * @todo   add event hook
+ *
  * @param  string $page the pagename you're looking for
  * @return string|false the full page id of the found page, false if any
  */
diff --git a/inc/parser/handler.php b/inc/parser/handler.php
index a1040d12e..0e7b294e5 100644
--- a/inc/parser/handler.php
+++ b/inc/parser/handler.php
@@ -711,6 +711,9 @@ class Doku_Handler_CallWriter {
 
     var $Handler;
 
+    /**
+     * @param Doku_Handler $Handler
+     */
     function Doku_Handler_CallWriter(& $Handler) {
         $this->Handler = & $Handler;
     }
@@ -747,7 +750,7 @@ class Doku_Handler_Nest {
     /**
      * constructor
      *
-     * @param  object     $CallWriter     the renderers current call writer
+     * @param  Doku_Handler_CallWriter $CallWriter     the renderers current call writer
      * @param  string     $close          closing instruction name, this is required to properly terminate the
      *                                    syntax mode if the document ends without a closing pattern
      */
diff --git a/inc/parser/renderer.php b/inc/parser/renderer.php
index 09294539e..6c074e43e 100644
--- a/inc/parser/renderer.php
+++ b/inc/parser/renderer.php
@@ -190,7 +190,7 @@ class Doku_Renderer extends DokuWiki_Plugin {
     /**
      * Render plain text data
      *
-     * @param $text
+     * @param string $text
      */
     function cdata($text) {
     }
@@ -759,6 +759,9 @@ class Doku_Renderer extends DokuWiki_Plugin {
      * casing and special chars
      *
      * @author Andreas Gohr <andi@splitbrain.org>
+     *
+     * @param string $name
+     * @return string
      */
     function _simpleTitle($name) {
         global $conf;
@@ -778,6 +781,11 @@ class Doku_Renderer extends DokuWiki_Plugin {
 
     /**
      * Resolve an interwikilink
+     *
+     * @param string    $shortcut  identifier for the interwiki link
+     * @param string    $reference fragment that refers the content
+     * @param null|bool $exists    reference which returns if an internal page exists
+     * @return string interwikilink
      */
     function _resolveInterWiki(&$shortcut, $reference, &$exists = null) {
         //get interwiki URL
diff --git a/inc/parser/xhtml.php b/inc/parser/xhtml.php
index aa09058df..c17c984d6 100644
--- a/inc/parser/xhtml.php
+++ b/inc/parser/xhtml.php
@@ -58,10 +58,11 @@ class Doku_Renderer_xhtml extends Doku_Renderer {
     /**
      * Register a new edit section range
      *
-     * @param $type  string The section type identifier
-     * @param $title string The section title
-     * @param $start int    The byte position for the edit start
-     * @return string A marker class for the starting HTML element
+     * @param string $type   The section type identifier
+     * @param string $title  The section title
+     * @param int    $start  The byte position for the edit start
+     * @return string  A marker class for the starting HTML element
+     *
      * @author Adrian Lang <lang@cosmocode.de>
      */
     public function startSectionEdit($start, $type, $title = null) {
@@ -72,8 +73,8 @@ class Doku_Renderer_xhtml extends Doku_Renderer {
     /**
      * Finish an edit section range
      *
-     * @param $end     int The byte position for the edit end; null for the rest of
-     *                 the page
+     * @param int  $end     The byte position for the edit end; null for the rest of the page
+     *
      * @author Adrian Lang <lang@cosmocode.de>
      */
     public function finishSectionEdit($end = null) {
diff --git a/inc/parserutils.php b/inc/parserutils.php
index 9c2a0b570..791033e63 100644
--- a/inc/parserutils.php
+++ b/inc/parserutils.php
@@ -55,6 +55,11 @@ define('METADATA_RENDER_UNLIMITED', 4);
  * wasn't found
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @param string|int $rev revision timestamp or empty string
+ * @param bool $excuse
+ * @return null|string
  */
 function p_wiki_xhtml($id, $rev='', $excuse=true){
     $file = wikiFN($id,$rev);
@@ -89,6 +94,9 @@ function p_wiki_xhtml($id, $rev='', $excuse=true){
  * Returns the specified local text in parsed format
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @return null|string
  */
 function p_locale_xhtml($id){
     //fetch parsed locale
@@ -101,6 +109,11 @@ function p_locale_xhtml($id){
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Chris Smith <chris@jalakai.co.uk>
+ *
+ * @param string $file filename, path to file
+ * @param string $format
+ * @param string $id page id
+ * @return null|string
  */
 function p_cached_output($file, $format='xhtml', $id='') {
     global $conf;
@@ -129,6 +142,11 @@ function p_cached_output($file, $format='xhtml', $id='') {
  * Uses and creates a serialized cache file
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file      filename, path to file
+ * @param bool   $cacheonly
+ * @param string $id        page id
+ * @return array|null
  */
 function p_cached_instructions($file,$cacheonly=false,$id='') {
     static $run = null;
@@ -157,7 +175,8 @@ function p_cached_instructions($file,$cacheonly=false,$id='') {
  *
  * @author Harry Fuecks <hfuecks@gmail.com>
  * @author Andreas Gohr <andi@splitbrain.org>
- * @param string $text raw wiki syntax text
+ *
+ * @param string $text  raw wiki syntax text
  * @return array a list of instruction arrays
  */
 function p_get_instructions($text){
@@ -185,9 +204,9 @@ function p_get_instructions($text){
 /**
  * returns the metadata of a page
  *
- * @param string $id The id of the page the metadata should be returned from
- * @param string $key The key of the metdata value that shall be read (by default everything) - separate hierarchies by " " like "date created"
- * @param int $render If the page should be rendererd - possible values:
+ * @param string $id      The id of the page the metadata should be returned from
+ * @param string $key     The key of the metdata value that shall be read (by default everything) - separate hierarchies by " " like "date created"
+ * @param int    $render  If the page should be rendererd - possible values:
  *     METADATA_DONT_RENDER, METADATA_RENDER_USING_SIMPLE_CACHE, METADATA_RENDER_USING_CACHE
  *     METADATA_RENDER_UNLIMITED (also combined with the previous two options),
  *     default: METADATA_RENDER_USING_CACHE
@@ -360,6 +379,9 @@ function p_set_metadata($id, $data, $render=false, $persistent=true){
  * used on page deletion
  *
  * @author Michael Klier <chi@chimeric.de>
+ *
+ * @param string $id page id
+ * @return bool  success / fail
  */
 function p_purge_metadata($id) {
     $meta = p_read_metadata($id);
@@ -423,6 +445,10 @@ function p_save_metadata($id, $meta) {
  * renders the metadata of a page
  *
  * @author Esther Brunner <esther@kaffeehaus.ch>
+ *
+ * @param string $id    page id
+ * @param array  $orig  the original metadata
+ * @return array|null array('current'=> array,'persistent'=> array);
  */
 function p_render_metadata($id, $orig){
     // make sure the correct ID is in global ID
@@ -477,6 +503,8 @@ function p_render_metadata($id, $orig){
  * returns all available parser syntax modes in correct order
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return array[] with for each plugin the array('sort' => sortnumber, 'mode' => mode string, 'obj'  => plugin object)
  */
 function p_get_parsermodes(){
     global $conf;
@@ -569,6 +597,10 @@ function p_get_parsermodes(){
  * Callback function for usort
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $a
+ * @param array $b
+ * @return int $a is lower/equal/higher than $b
  */
 function p_sort_modes($a, $b){
     if($a['sort'] == $b['sort']) return 0;
@@ -582,6 +614,11 @@ function p_sort_modes($a, $b){
  *
  * @author Harry Fuecks <hfuecks@gmail.com>
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $mode
+ * @param array  $instructions
+ * @param array  $info returns render info like enabled toc and cache
+ * @return null|string rendered output
  */
 function p_render($mode,$instructions,&$info){
     if(is_null($instructions)) return '';
@@ -673,8 +710,8 @@ function p_get_renderer($mode) {
  *                                              METADATA_RENDER_USING_SIMPLE_CACHE,
  *                                              METADATA_RENDER_USING_CACHE,
  *                                              METADATA_RENDER_UNLIMITED
- *
  * @return string|null The first heading
+ *
  * @author Andreas Gohr <andi@splitbrain.org>
  * @author Michael Hamann <michael@content-space.de>
  */
@@ -688,8 +725,8 @@ function p_get_first_heading($id, $render=METADATA_RENDER_USING_SIMPLE_CACHE){
  * @param  string   $code       source code to be highlighted
  * @param  string   $language   language to provide highlighting
  * @param  string   $wrapper    html element to wrap the returned highlighted text
- *
  * @return string xhtml code
+ *
  * @author Christopher Smith <chris@jalakai.co.uk>
  * @author Andreas Gohr <andi@splitbrain.org>
  */
diff --git a/inc/plugin.php b/inc/plugin.php
index fbfc0325f..8432b21b2 100644
--- a/inc/plugin.php
+++ b/inc/plugin.php
@@ -48,14 +48,25 @@ class DokuWiki_Plugin {
 
     // plugin introspection methods
     // extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
+    /**
+     * @return string  plugin type
+     */
     function getPluginType() {
         list($t) = explode('_', get_class($this), 2);
         return $t;
     }
+
+    /**
+     * @return string  plugin name
+     */
     function getPluginName() {
         list($t, $p, $n) = explode('_', get_class($this), 4);
         return $n;
     }
+
+    /**
+     * @return string  component name
+     */
     function getPluginComponent() {
         list($t, $p, $n, $c) = explode('_', get_class($this), 4);
         return (isset($c)?$c:'');
@@ -91,9 +102,11 @@ class DokuWiki_Plugin {
     }
 
     /**
-     * localFN($id)
-     * prepends appropriate path for a language dependent filename
+     * Prepends appropriate path for a language dependent filename
      * plugin equivalent of localFN()
+     *
+     * @param string $id id of localization file
+     * @return string wiki text
      */
     function localFN($id) {
         global $conf;
@@ -110,9 +123,8 @@ class DokuWiki_Plugin {
     }
 
     /**
-     *  setupLocale()
-     *  reads all the plugins language dependent strings into $this->lang
-     *  this function is automatically called by getLang()
+     * Reads all the plugins language dependent strings into $this->lang
+     * this function is automatically called by getLang()
      */
     function setupLocale() {
         if ($this->localised) return;
@@ -196,8 +208,7 @@ class DokuWiki_Plugin {
      *
      * @param   string $name   name of plugin to load
      * @param   bool   $msg    if a message should be displayed in case the plugin is not available
-     *
-     * @return  object  helper plugin object
+     * @return  DokuWiki_Plugin|null helper plugin object
      */
     function loadHelper($name, $msg = true){
         $obj = plugin_load('helper',$name);
@@ -211,6 +222,12 @@ class DokuWiki_Plugin {
     /**
      * email
      * standardised function to generate an email link according to obfuscation settings
+     *
+     * @param string $email
+     * @param string $name
+     * @param string $class
+     * @param string $more
+     * @return string html
      */
     function email($email, $name='', $class='', $more='') {
         if (!$email) return $name;
@@ -223,6 +240,13 @@ class DokuWiki_Plugin {
     /**
      * external_link
      * standardised function to generate an external link according to conf settings
+     *
+     * @param string $link
+     * @param string $title
+     * @param string $class
+     * @param string $target
+     * @param string $more
+     * @return string
      */
     function external_link($link, $title='', $class='', $target='', $more='') {
         global $conf;
@@ -247,8 +271,9 @@ class DokuWiki_Plugin {
      * Instead use render_text()
      *
      * @deprecated 2014-01-22
-     * @param $name
-     * @param $arguments
+     *
+     * @param string $name
+     * @param array  $arguments
      * @return null|string
      */
     function __call($name, $arguments) {
@@ -265,7 +290,7 @@ class DokuWiki_Plugin {
      * output text string through the parser, allows dokuwiki markup to be used
      * very ineffecient for small pieces of data - try not to use
      *
-     * @param string $text wiki markup to parse
+     * @param string $text   wiki markup to parse
      * @param string $format output format
      * @return null|string
      */
diff --git a/inc/plugincontroller.class.php b/inc/plugincontroller.class.php
index 86c10585e..21d227ee4 100644
--- a/inc/plugincontroller.class.php
+++ b/inc/plugincontroller.class.php
@@ -114,7 +114,7 @@ class Doku_Plugin_Controller {
      * Whether plugin is disabled
      *
      * @param string $plugin name of plugin
-     * @return bool; true disabled, false enabled
+     * @return bool  true disabled, false enabled
      */
     public function isdisabled($plugin) {
         return empty($this->tmp_plugins[$plugin]);
@@ -124,7 +124,7 @@ class Doku_Plugin_Controller {
      * Disable the plugin
      *
      * @param string $plugin name of plugin
-     * @return bool; true saving succeed, false saving failed
+     * @return bool  true saving succeed, false saving failed
      */
     public function disable($plugin) {
         if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false;
@@ -136,7 +136,7 @@ class Doku_Plugin_Controller {
      * Enable the plugin
      *
      * @param string $plugin name of plugin
-     * @return bool; true saving succeed, false saving failed
+     * @return bool  true saving succeed, false saving failed
      */
     public function enable($plugin) {
         if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false;
@@ -227,7 +227,7 @@ class Doku_Plugin_Controller {
      * @param bool $forceSave;
      *              false to save only when config changed
      *              true to always save
-     * @return bool; true saving succeed, false saving failed
+     * @return bool  true saving succeed, false saving failed
      */
     protected function saveList($forceSave = false) {
         global $conf;
@@ -300,12 +300,9 @@ class Doku_Plugin_Controller {
     /**
      * Returns a list of available plugin components of given type
      *
-     * @param string $type, plugin_type name;
-     *                      the type of plugin to return,
-     * @param bool   $enabled;
-     *                      true to return enabled plugins,
-     *                      false to return disabled plugins
-     *
+     * @param string $type      plugin_type name; the type of plugin to return,
+     * @param bool   $enabled   true to return enabled plugins,
+     *                          false to return disabled plugins
      * @return array of plugin components of requested type
      */
     protected function _getListByType($type, $enabled) {
diff --git a/inc/remote.php b/inc/remote.php
index a21ef1e25..861353a19 100644
--- a/inc/remote.php
+++ b/inc/remote.php
@@ -60,6 +60,9 @@ class RemoteAPI {
     private $dateTransformation;
     private $fileTransformation;
 
+    /**
+     * constructor
+     */
     public function __construct() {
         $this->dateTransformation = array($this, 'dummyTransformation');
         $this->fileTransformation = array($this, 'dummyTransformation');
@@ -75,7 +78,7 @@ class RemoteAPI {
     }
 
     /**
-     * call a method via remote api.
+     * Call a method via remote api.
      *
      * @param string $method name of the method to call.
      * @param array $args arguments to pass to the given method
@@ -95,11 +98,25 @@ class RemoteAPI {
         return $this->callCustomCallPlugin($method, $args);
     }
 
+    /**
+     * Check existance of core methods
+     *
+     * @param string $name name of the method
+     * @return bool if method exists
+     */
     private function coreMethodExist($name) {
         $coreMethods = $this->getCoreMethods();
         return array_key_exists($name, $coreMethods);
     }
 
+    /**
+     * Try to call custom methods provided by plugins
+     *
+     * @param string $method name of method
+     * @param array  $args
+     * @return mixed
+     * @throws RemoteException if method not exists
+     */
     private function  callCustomCallPlugin($method, $args) {
         $customCalls = $this->getCustomCallPlugins();
         if (!array_key_exists($method, $customCalls)) {
@@ -109,6 +126,12 @@ class RemoteAPI {
         return $this->callPlugin($customCall[0], $customCall[1], $args);
     }
 
+    /**
+     * Returns plugin calls that are registered via RPC_CALL_ADD action
+     *
+     * @return array with pairs of custom plugin calls
+     * @triggers RPC_CALL_ADD
+     */
     private function getCustomCallPlugins() {
         if ($this->pluginCustomCalls === null) {
             $data = array();
@@ -118,6 +141,15 @@ class RemoteAPI {
         return $this->pluginCustomCalls;
     }
 
+    /**
+     * Call a plugin method
+     *
+     * @param string $pluginName
+     * @param string $method method name
+     * @param array  $args
+     * @return mixed return of custom method
+     * @throws RemoteException
+     */
     private function callPlugin($pluginName, $method, $args) {
         $plugin = plugin_load('remote', $pluginName);
         $methods = $this->getPluginMethods();
@@ -129,6 +161,14 @@ class RemoteAPI {
         return call_user_func_array(array($plugin, $name), $args);
     }
 
+    /**
+     * Call a core method
+     *
+     * @param string $method name of method
+     * @param array  $args
+     * @return mixed
+     * @throws RemoteException if method not exist
+     */
     private function callCoreMethod($method, $args) {
         $coreMethods = $this->getCoreMethods();
         $this->checkAccess($coreMethods[$method]);
@@ -139,6 +179,11 @@ class RemoteAPI {
         return call_user_func_array(array($this->coreMethods, $this->getMethodName($coreMethods, $method)), $args);
     }
 
+    /**
+     * Check if access should be checked
+     *
+     * @param array $methodMeta data about the method
+     */
     private function checkAccess($methodMeta) {
         if (!isset($methodMeta['public'])) {
             $this->forceAccess();
@@ -149,12 +194,26 @@ class RemoteAPI {
         }
     }
 
-    private function checkArgumentLength($method, $args) {
-        if (count($method['args']) < count($args)) {
+    /**
+     * Check the number of parameters
+     *
+     * @param array $methodMeta data about the method
+     * @param array $args
+     * @throws RemoteException if wrong parameter count
+     */
+    private function checkArgumentLength($methodMeta, $args) {
+        if (count($methodMeta['args']) < count($args)) {
             throw new RemoteException('Method does not exist - wrong parameter count.', -32603);
         }
     }
 
+    /**
+     * Determine the name of the real method
+     *
+     * @param array $methodMeta list of data of the methods
+     * @param string $method name of method
+     * @return string
+     */
     private function getMethodName($methodMeta, $method) {
         if (isset($methodMeta[$method]['name'])) {
             return $methodMeta[$method]['name'];
@@ -164,6 +223,8 @@ class RemoteAPI {
     }
 
     /**
+     * Perform access check for current user
+     *
      * @return bool true if the current user has access to remote api.
      */
     public function hasAccess() {
@@ -186,8 +247,10 @@ class RemoteAPI {
     }
 
     /**
-     * @throws RemoteException On denied access.
+     * Requests access
+     *
      * @return void
+     * @throws RemoteException On denied access.
      */
     public function forceAccess() {
         if (!$this->hasAccess()) {
@@ -196,7 +259,10 @@ class RemoteAPI {
     }
 
     /**
+     * Collects all the methods of the enabled Remote Plugins
+     *
      * @return array all plugin methods.
+     * @throws RemoteException if not implemented
      */
     public function getPluginMethods() {
         if ($this->pluginMethods === null) {
@@ -204,6 +270,7 @@ class RemoteAPI {
             $plugins = plugin_list('remote');
 
             foreach ($plugins as $pluginName) {
+                /** @var DokuWiki_Remote_Plugin $plugin */
                 $plugin = plugin_load('remote', $pluginName);
                 if (!is_subclass_of($plugin, 'DokuWiki_Remote_Plugin')) {
                     throw new RemoteException("Plugin $pluginName does not implement DokuWiki_Remote_Plugin");
@@ -219,6 +286,8 @@ class RemoteAPI {
     }
 
     /**
+     * Collects all the core methods
+     *
      * @param RemoteAPICore $apiCore this parameter is used for testing. Here you can pass a non-default RemoteAPICore
      *                               instance. (for mocking)
      * @return array all core methods.
@@ -234,22 +303,50 @@ class RemoteAPI {
         return $this->coreMethods->__getRemoteInfo();
     }
 
+    /**
+     * Transform file to xml
+     *
+     * @param mixed $data
+     * @return mixed
+     */
     public function toFile($data) {
         return call_user_func($this->fileTransformation, $data);
     }
 
+    /**
+     * Transform date to xml
+     *
+     * @param mixed $data
+     * @return mixed
+     */
     public function toDate($data) {
         return call_user_func($this->dateTransformation, $data);
     }
 
+    /**
+     * A simple transformation
+     *
+     * @param mixed $data
+     * @return mixed
+     */
     public function dummyTransformation($data) {
         return $data;
     }
 
+    /**
+     * Set the transformer function
+     *
+     * @param callback $dateTransformation
+     */
     public function setDateTransformation($dateTransformation) {
         $this->dateTransformation = $dateTransformation;
     }
 
+    /**
+     * Set the transformer function
+     *
+     * @param callback $fileTransformation
+     */
     public function setFileTransformation($fileTransformation) {
         $this->fileTransformation = $fileTransformation;
     }
diff --git a/inc/search.php b/inc/search.php
index 79d930149..935969d3f 100644
--- a/inc/search.php
+++ b/inc/search.php
@@ -134,6 +134,11 @@ function search_namespaces(&$data,$base,$file,$type,$lvl,$opts){
 
 /**
  * List all mediafiles in a namespace
+ *   $opts['depth']     recursion level, 0 for all
+ *   $opts['showmsg']   shows message if invalid media id is used
+ *   $opts['skipacl']   skip acl checking
+ *   $opts['pattern']   check given pattern
+ *   $opts['hash']      add hashes to result list
  *
  * @author  Andreas Gohr <andi@splitbrain.org>
  */
diff --git a/inc/subscription.php b/inc/subscription.php
index bad98cf6c..58376f2ec 100644
--- a/inc/subscription.php
+++ b/inc/subscription.php
@@ -444,11 +444,11 @@ class Subscription {
      * Send the diff for some media change
      *
      * @fixme this should embed thumbnails of images in HTML version
+     *
      * @param string   $subscriber_mail The target mail address
      * @param string   $template        Mail template ('uploadmail', ...)
      * @param string   $id              Media file for which the notification is
      * @param int|bool $rev             Old revision if any
-     * @return bool                     true if successfully sent
      */
     public function send_media_diff($subscriber_mail, $template, $id, $rev = false) {
         global $conf;
@@ -619,6 +619,7 @@ class Subscription {
 
     /**
      * Get a valid message id for a certain $id and revision (or the current revision)
+     *
      * @param string $id  The id of the page (or media file) the message id should be for
      * @param string $rev The revision of the page, set to the current revision of the page $id if not set
      * @return string
diff --git a/inc/template.php b/inc/template.php
index 49f6986fd..98ea9df82 100644
--- a/inc/template.php
+++ b/inc/template.php
@@ -68,6 +68,7 @@ function tpl_basedir($tpl='') {
  * handled by this function. ACL stuff is not done here either.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @triggers TPL_ACT_RENDER
  * @triggers TPL_CONTENT_DISPLAY
  * @param bool $prependTOC should the TOC be displayed here?
@@ -186,6 +187,7 @@ function tpl_content_core() {
  * a false argument
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param bool $return Should the TOC be returned instead to be printed?
  * @return string
  */
@@ -243,6 +245,8 @@ function tpl_toc($return = false) {
  * Handle the admin page contents
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @return bool
  */
 function tpl_admin() {
     global $INFO;
@@ -277,6 +281,7 @@ function tpl_admin() {
  * This has to go into the head section of your template.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @triggers TPL_METAHEADER_OUTPUT
  * @param  bool $alt Should feeds and alternative format links be added?
  * @return bool
@@ -426,10 +431,12 @@ function tpl_metaheaders($alt = true) {
  * instances. Attributes are given as key value pairs. Values will be HTML
  * encoded automatically so they should be provided as is in the $data array.
  *
- * For tags having a body attribute specify the the body data in the special
+ * For tags having a body attribute specify the body data in the special
  * attribute '_data'. This field will NOT BE ESCAPED automatically.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param array $data
  */
 function _tpl_metaheaders_action($data) {
     foreach($data as $tag => $inst) {
@@ -456,6 +463,12 @@ function _tpl_metaheaders_action($data) {
  * Just builds a link.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $url
+ * @param string $name
+ * @param string $more
+ * @param bool $return return html
+ * @return bool|string html or true
  */
 function tpl_link($url, $name, $more = '', $return = false) {
     $out = '<a href="'.$url.'" ';
@@ -472,6 +485,10 @@ function tpl_link($url, $name, $more = '', $return = false) {
  * Wrapper around html_wikilink
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string      $id   page id
+ * @param string|null $name the name of the link
+ * @return bool
  */
 function tpl_pagelink($id, $name = null) {
     print '<bdi>'.html_wikilink($id, $name).'</bdi>';
@@ -485,6 +502,9 @@ function tpl_pagelink($id, $name = null) {
  * returns false if none is available
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $id page id
+ * @return false|string
  */
 function tpl_getparent($id) {
     $parent = getNS($id).':';
@@ -539,7 +559,7 @@ function tpl_button($type, $return = false) {
  * @author Adrian Lang <mail@adrianlang.de>
  * @see    tpl_get_action
  *
- * @param string $type
+ * @param string $type action command
  * @param string $pre prefix of link
  * @param string $suf suffix of link
  * @param string $inner innerHML of link
@@ -767,7 +787,8 @@ function tpl_get_action($type) {
  * Wrapper around tpl_button() and tpl_actionlink()
  *
  * @author Anika Henke <anika@selfthinker.org>
- * @param
+ *
+ * @param string        $type action command
  * @param bool          $link link or form button?
  * @param string|bool   $wrapper HTML element wrapper
  * @param bool          $return return or print
@@ -801,6 +822,7 @@ function tpl_action($type, $link = false, $wrapper = false, $return = false, $pr
  * autocompletion feature (MSIE and Firefox)
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param bool $ajax
  * @param bool $autocomplete
  * @return bool
@@ -829,6 +851,7 @@ function tpl_searchform($ajax = true, $autocomplete = true) {
  * Print the breadcrumbs trace
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $sep Separator between entries
  * @return bool
  */
@@ -870,6 +893,7 @@ function tpl_breadcrumbs($sep = '•') {
  * @author Sean Coates <sean@caedmon.net>
  * @author <fredrik@averpil.com>
  * @todo   May behave strangely in RTL languages
+ *
  * @param string $sep Separator between entries
  * @return bool
  */
@@ -920,6 +944,7 @@ function tpl_youarehere($sep = ' » ') {
  * Could be enhanced with a profile link in future?
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @return bool
  */
 function tpl_userinfo() {
@@ -938,6 +963,7 @@ function tpl_userinfo() {
  * Print some info about the current page
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param bool $ret return content instead of printing it
  * @return bool|string
  */
@@ -1001,6 +1027,7 @@ function tpl_pageinfo($ret = false) {
  * the given ID is used.
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param string $id page id
  * @param bool   $ret return content instead of printing
  * @return bool|string
@@ -1038,6 +1065,7 @@ function tpl_pagetitle($id = null, $ret = false) {
  * Only allowed in: detail.php
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
  * @param array  $tags tags to try
  * @param string $alt alternative output if no data was found
  * @param null|string   $src the image src, uses global $SRC if not given
@@ -1128,7 +1156,7 @@ function tpl_get_img_meta() {
  * @param $maxheight int - maximal height of the image
  * @param $link bool     - link to the orginal size?
  * @param $params array  - additional image attributes
- * @return mixed Result of TPL_IMG_DISPLAY
+ * @return bool Result of TPL_IMG_DISPLAY
  */
 function tpl_img($maxwidth = 0, $maxheight = 0, $link = true, $params = null) {
     global $IMG;
@@ -1280,6 +1308,9 @@ function tpl_loadConfig() {
  * tpl_getLang($id)
  *
  * use this function to access template language variables
+ *
+ * @param string $id key of language string
+ * @return string
  */
 function tpl_getLang($id) {
     static $lang = array();
@@ -1311,6 +1342,9 @@ function tpl_locale_xhtml($id) {
 
 /**
  * Prepends appropriate path for a language dependent filename
+ *
+ * @param string $id id of localized text
+ * @return string wiki text
  */
 function tpl_localeFN($id) {
     $path = tpl_incdir().'lang/';
@@ -1337,6 +1371,8 @@ function tpl_localeFN($id) {
  *
  * @triggers MEDIAMANAGER_CONTENT_OUTPUT
  * @param bool $fromajax - set true when calling this function via ajax
+ * @param string $sort
+
  * @author Andreas Gohr <andi@splitbrain.org>
  */
 function tpl_mediaContent($fromajax = false, $sort='natural') {
@@ -1511,6 +1547,9 @@ function tpl_mediaTree() {
  * Note: this will not use any pretty URLs
  *
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $empty empty option label
+ * @param string $button submit button label
  */
 function tpl_actiondropdown($empty = '', $button = '&gt;') {
     global $ID;
@@ -1737,10 +1776,11 @@ function tpl_flush() {
  * If a given location starts with a colon it is assumed to be a media
  * file, otherwise it is assumed to be relative to the current template
  *
- * @param  array $search       locations to look at
- * @param  bool  $abs           if to use absolute URL
- * @param  array &$imginfo   filled with getimagesize()
+ * @param  string[] $search       locations to look at
+ * @param  bool     $abs           if to use absolute URL
+ * @param  array   &$imginfo   filled with getimagesize()
  * @return string
+ *
  * @author Andreas  Gohr <andi@splitbrain.org>
  */
 function tpl_getMediaFile($search, $abs = false, &$imginfo = null) {
@@ -1791,6 +1831,8 @@ function tpl_getMediaFile($search, $abs = false, &$imginfo = null) {
  *
  * @author Anika Henke <anika@selfthinker.org>
  * @author Andreas Gohr <andi@splitbrain.org>
+ *
+ * @param string $file
  */
 function tpl_includeFile($file) {
     global $config_cascade;
@@ -1816,6 +1858,7 @@ function tpl_includeFile($file) {
  * Returns <link> tag for various icon types (favicon|mobile|generic)
  *
  * @author Anika Henke <anika@selfthinker.org>
+ *
  * @param  array $types - list of icon types to display (favicon|mobile|generic)
  * @return string
  */
@@ -1891,6 +1934,8 @@ function tpl_media() {
  * Return useful layout classes
  *
  * @author Anika Henke <anika@selfthinker.org>
+ *
+ * @return string
  */
 function tpl_classes() {
     global $ACT, $conf, $ID, $INFO;
diff --git a/lib/exe/xmlrpc.php b/lib/exe/xmlrpc.php
index c09daa17c..3a878ebe4 100644
--- a/lib/exe/xmlrpc.php
+++ b/lib/exe/xmlrpc.php
@@ -40,10 +40,18 @@ class dokuwiki_xmlrpc_server extends IXR_Server {
         }
     }
 
+    /**
+     * @param string|int $data iso date(yyyy[-]mm[-]dd[ hh:mm[:ss]]) or timestamp
+     * @return IXR_Date
+     */
     function toDate($data) {
         return new IXR_Date($data);
     }
 
+    /**
+     * @param string $data
+     * @return IXR_Base64
+     */
     function toFile($data) {
         return new IXR_Base64($data);
     }
diff --git a/lib/plugins/acl/remote.php b/lib/plugins/acl/remote.php
index 2fdc697db..b10c544ee 100644
--- a/lib/plugins/acl/remote.php
+++ b/lib/plugins/acl/remote.php
@@ -1,7 +1,16 @@
 <?php
 
+/**
+ * Class remote_plugin_acl
+ */
 class remote_plugin_acl extends DokuWiki_Remote_Plugin {
-    function _getMethods() {
+
+    /**
+     * Returns details about the remote plugin methods
+     *
+     * @return array
+     */
+    public function _getMethods() {
         return array(
             'addAcl' => array(
                 'args' => array('string','string','int'),
@@ -17,13 +26,28 @@ class remote_plugin_acl extends DokuWiki_Remote_Plugin {
         );
     }
 
-    function addAcl($scope, $user, $level){
+    /**
+     * Add a new entry to ACL config
+     *
+     * @param string $scope
+     * @param string $user
+     * @param int    $level see also inc/auth.php
+     * @return bool
+     */
+    public function addAcl($scope, $user, $level){
         /** @var admin_plugin_acl $apa */
         $apa = plugin_load('admin', 'acl');
         return $apa->_acl_add($scope, $user, $level);
     }
 
-    function delAcl($scope, $user){
+    /**
+     * Remove an entry from ACL config
+     *
+     * @param string $scope
+     * @param string $user
+     * @return bool
+     */
+    public function delAcl($scope, $user){
         /** @var admin_plugin_acl $apa */
         $apa = plugin_load('admin', 'acl');
         return $apa->_acl_del($scope, $user);