Fixed and extended PHPDoc comments and added additional @var comments

6 files changed, 57 insertions, 21 deletions

diff --git a/_test/core/DokuWikiTest.php b/_test/core/DokuWikiTest.php
index e51f1eeb1..b9e151456 100644
--- a/_test/core/DokuWikiTest.php
+++ b/_test/core/DokuWikiTest.php
@@ -78,6 +78,7 @@ abstract class DokuWikiTest extends PHPUnit_Framework_TestCase {
 
         // reset loaded plugins
         global $plugin_controller_class, $plugin_controller;
+        /** @var Doku_Plugin_Controller $plugin_controller */
         $plugin_controller = new $plugin_controller_class();
 
         // disable all non-default plugins
diff --git a/inc/confutils.php b/inc/confutils.php
index 29ead1e9f..edea80092 100644
--- a/inc/confutils.php
+++ b/inc/confutils.php
@@ -115,7 +115,11 @@ function getWordblocks() {
     return $wordblocks;
 }
 
-
+/**
+ * Gets the list of configured schemes
+ *
+ * @return array the schemes
+ */
 function getSchemes() {
     static $schemes = null;
     if ( !$schemes ) {
@@ -182,7 +186,7 @@ function confToHash($file,$lower=false) {
  *
  * @param  string   $type     the configuration settings to be read, must correspond to a key/array in $config_cascade
  * @param  callback $fn       the function used to process the configuration file into an array
- * @param  array    $param    optional additional params to pass to the callback
+ * @param  array    $params   optional additional params to pass to the callback
  * @return array    configuration values
  */
 function retrieveConfig($type,$fn,$params=null) {
@@ -236,6 +240,7 @@ function actionOK($action){
     static $disabled = null;
     if(is_null($disabled)){
         global $conf;
+        /** @var auth_basic $auth */
         global $auth;
 
         // prepare disabled actions array and handle legacy options
@@ -272,7 +277,7 @@ function actionOK($action){
  *
  * @param   string  $linktype   'content'|'navigation', content applies to links in wiki text
  *                                                      navigation applies to all other links
- * @returns boolean             true if headings should be used for $linktype, false otherwise
+ * @return  boolean             true if headings should be used for $linktype, false otherwise
  */
 function useHeading($linktype) {
     static $useHeading = null;
diff --git a/inc/indexer.php b/inc/indexer.php
index c28499d68..321940508 100644
--- a/inc/indexer.php
+++ b/inc/indexer.php
@@ -463,8 +463,8 @@ class Doku_Indexer {
      * in the returned list is an array with the page names as keys and the
      * number of times that token appears on the page as value.
      *
-     * @param arrayref  $tokens list of words to search for
-     * @return array            list of page names with usage counts
+     * @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>
      */
@@ -615,9 +615,9 @@ class Doku_Indexer {
      * The $result parameter can be used to merge the index locations with
      * the appropriate query term.
      *
-     * @param arrayref  $words  The query terms.
-     * @param arrayref  $result Set to word => array("length*id" ...)
-     * @return array            Set to length => array(id ...)
+     * @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) {
@@ -728,7 +728,7 @@ class Doku_Indexer {
      *
      * @param int       $min    bottom frequency threshold
      * @param int       $max    upper frequency limit. No limit if $max<$min
-     * @param int       $length minimum length of words to count
+     * @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>
@@ -852,7 +852,8 @@ class Doku_Indexer {
      *
      * @param string    $idx    name of the index
      * @param string    $suffix subpart identifier
-     * @param arrayref  $linex  list of lines without LF
+     * @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) {
@@ -902,6 +903,7 @@ class Doku_Indexer {
      * @param string    $suffix subpart identifier
      * @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) {
@@ -961,6 +963,11 @@ class Doku_Indexer {
         return $id;
     }
 
+    /**
+     * @param string $idx    The index file which should be added to the key.
+     * @param string $suffix The suffix of the file
+     * @param bool   $delete Unused
+     */
     protected function cacheIndexDir($idx, $suffix, $delete=false) {
         global $conf;
         if ($idx == 'i')
@@ -1263,8 +1270,8 @@ function idx_addPage($page, $verbose=false, $force=false) {
  * Important: No ACL checking is done here! All results are
  *            returned, regardless of permissions
  *
- * @param arrayref      $words  list of words to search for
- * @return array                list of pages found, associated with the search terms
+ * @param array      $words  list of words to search for
+ * @return array             list of pages found, associated with the search terms
  */
 function idx_lookup(&$words) {
     $Indexer = idx_get_indexer();
diff --git a/inc/parser/parser.php b/inc/parser/parser.php
index cf132ce97..98fb7939c 100644
--- a/inc/parser/parser.php
+++ b/inc/parser/parser.php
@@ -52,6 +52,9 @@ class Doku_Parser {
 
     var $Handler;
 
+    /**
+     * @var Doku_Lexer $Lexer
+     */
     var $Lexer;
 
     var $modes = array();
@@ -134,6 +137,9 @@ class Doku_Parser {
 */
 class Doku_Parser_Mode {
 
+    /**
+     * @var Doku_Lexer $Lexer
+     */
     var $Lexer;
 
     var $allowedModes = array();
diff --git a/inc/parserutils.php b/inc/parserutils.php
index f182b84c4..107c42eb0 100644
--- a/inc/parserutils.php
+++ b/inc/parserutils.php
@@ -92,8 +92,11 @@ function p_wiki_xhtml($id, $rev='', $excuse=true){
  * If $excuse is true an explanation is returned if the file
  * wasn't found
  *
- * @param string wiki page id
- * @param reference populated with page title from heading or page id
+ * @param string $id wiki page id
+ * @param string $title populated with page title from heading or page id
+ * @param string $rev revision string
+ * @param bool   $excuse if an excuse shall be renderer when no content is found
+ * @return string xhtml code
  * @deprecated
  * @author Harry Fuecks <hfuecks@gmail.com>
  */
@@ -565,6 +568,7 @@ function p_get_parsermodes(){
         global $PARSER_MODES;
         $obj = null;
         foreach($pluginlist as $p){
+            /** @var DokuWiki_Syntax_Plugin $obj */
             if(!$obj =& plugin_load('syntax',$p)) continue; //attempt to load plugin into $obj
             $PARSER_MODES[$obj->getType()][] = "plugin_$p"; //register mode type
             //add to modes
@@ -675,7 +679,12 @@ function p_render($mode,$instructions,&$info){
     return $Renderer->doc;
 }
 
+/**
+ * @param $mode string Mode of the renderer to get
+ * @return null|Doku_Renderer The renderer
+ */
 function & p_get_renderer($mode) {
+    /** @var Doku_Plugin_Controller $plugin_controller */
     global $conf, $plugin_controller;
 
     $rname = !empty($conf['renderer_'.$mode]) ? $conf['renderer_'.$mode] : $mode;
@@ -723,6 +732,7 @@ function & p_get_renderer($mode) {
  *                                              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>
  */
@@ -737,6 +747,7 @@ function p_get_first_heading($id, $render=METADATA_RENDER_USING_SIMPLE_CACHE){
  * @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/lib/plugins/syntax.php b/lib/plugins/syntax.php
index 12451f636..d4394eb6f 100644
--- a/lib/plugins/syntax.php
+++ b/lib/plugins/syntax.php
@@ -86,7 +86,7 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode {
      * @param   $match   string    The text matched by the patterns
      * @param   $state   int       The lexer state for the match
      * @param   $pos     int       The character position of the matched text
-     * @param   $handler ref       Reference to the Doku_Handler object
+     * @param   $handler Doku_Handler Reference to the Doku_Handler object
      * @return  array              Return an array with all data you want to use in render
      */
     function handle($match, $state, $pos, &$handler){
@@ -111,10 +111,10 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode {
      * The contents of the $data array depends on what the handler() function above
      * created
      *
-     * @param   $format   string   output format being rendered
-     * @param   $renderer ref      reference to the current renderer object
-     * @param   $data     array    data created by handler()
-     * @return  boolean            rendered correctly?
+     * @param   $format   string        output format being rendered
+     * @param   $renderer Doku_Renderer reference to the current renderer object
+     * @param   $data     array         data created by handler()
+     * @return  boolean                 rendered correctly?
      */
     function render($format, &$renderer, $data) {
         trigger_error('render() not implemented in '.get_class($this), E_USER_WARNING);
@@ -148,6 +148,12 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode {
     // extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
     function getPluginType() { list($t) = explode('_', get_class($this), 2); return $t;  }
     function getPluginName() { list($t, $p, $n) = explode('_', get_class($this), 4); return $n; }
+
+    /**
+     * Get the name of the component of the current class
+     *
+     * @return string component name
+     */
     function getPluginComponent() { list($t, $p, $n, $c) = explode('_', get_class($this), 4); return (isset($c)?$c:''); }
 
     // localisation methods
@@ -158,7 +164,7 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode {
      * to try to minimise unnecessary loading of the strings when the plugin doesn't require them
      * e.g. when info plugin is querying plugins for information about themselves.
      *
-     * @param   $id     id of the string to be retrieved
+     * @param   string $id     id of the string to be retrieved
      * @return  string  string in appropriate language or english if not available
      */
     function getLang($id) {
@@ -173,7 +179,7 @@ class DokuWiki_Syntax_Plugin extends Doku_Parser_Mode {
      * retrieve a language dependent wiki page and pass to xhtml renderer for display
      * plugin equivalent of p_locale_xhtml()
      *
-     * @param   $id     id of language dependent wiki page
+     * @param   string  $id     id of language dependent wiki page
      * @return  string  parsed contents of the wiki page in xhtml format
      */
     function locale_xhtml($id) {