Merge pull request #382 from splitbrain/visibilityPHPDocs

Visibility php docs

3 files changed, 172 insertions, 31 deletions

diff --git a/inc/plugincontroller.class.php b/inc/plugincontroller.class.php
index c825870cd..33d8c92cd 100644
--- a/inc/plugincontroller.class.php
+++ b/inc/plugincontroller.class.php
@@ -11,15 +11,15 @@ if(!defined('DOKU_PLUGIN'))  define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
 
 class Doku_Plugin_Controller {
 
-    var $list_bytype = array();
-    var $tmp_plugins = array();
-    var $plugin_cascade = array('default'=>array(),'local'=>array(),'protected'=>array());
-    var $last_local_config_file = '';
+    protected $list_bytype = array();
+    protected $tmp_plugins = array();
+    protected $plugin_cascade = array('default'=>array(),'local'=>array(),'protected'=>array());
+    protected $last_local_config_file = '';
 
     /**
      * Populates the master list of plugins
      */
-    function __construct() {
+    public function __construct() {
         $this->loadConfig();
         $this->_populateMasterList();
     }
@@ -34,11 +34,13 @@ class Doku_Plugin_Controller {
      *               false to only return enabled plugins,
      *               true to return both enabled and disabled plugins
      *
-     * @return       array of plugin names
+     * @return       array of
+     *                  - plugin names when $type = ''
+     *                  - or plugin component names when a $type is given
      *
      * @author Andreas Gohr <andi@splitbrain.org>
      */
-    function getList($type='',$all=false){
+    public function getList($type='',$all=false){
 
         // request the complete list
         if (!$type) {
@@ -64,9 +66,9 @@ class Doku_Plugin_Controller {
      * @param  $name     string name of the plugin to load
      * @param  $new      bool   true to return a new instance of the plugin, false to use an already loaded instance
      * @param  $disabled bool   true to load even disabled plugins
-     * @return objectreference  the plugin object or null on failure
+     * @return DokuWiki_Plugin|DokuWiki_Syntax_Plugin|null  the plugin object or null on failure
      */
-    function load($type,$name,$new=false,$disabled=false){
+    public function load($type,$name,$new=false,$disabled=false){
 
         //we keep all loaded plugins available in global scope for reuse
         global $DOKU_PLUGINS;
@@ -108,26 +110,59 @@ class Doku_Plugin_Controller {
         return $DOKU_PLUGINS[$type][$name];
     }
 
-    function isdisabled($plugin) {
+    /**
+     * Whether plugin is disabled
+     *
+     * @param string $plugin name of plugin
+     * @return bool; true disabled, false enabled
+     */
+    public function isdisabled($plugin) {
         return empty($this->tmp_plugins[$plugin]);
     }
 
-    function disable($plugin) {
+    /**
+     * Disable the plugin
+     *
+     * @param string $plugin name of plugin
+     * @return bool; true saving succeed, false saving failed
+     */
+    public function disable($plugin) {
         if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false;
         $this->tmp_plugins[$plugin] = 0;
         return $this->saveList();
     }
 
-    function enable($plugin) {
+    /**
+     * Enable the plugin
+     *
+     * @param string $plugin name of plugin
+     * @return bool; true saving succeed, false saving failed
+     */
+    public function enable($plugin) {
         if(array_key_exists($plugin,$this->plugin_cascade['protected'])) return false;
         $this->tmp_plugins[$plugin] = 1;
         return $this->saveList();
     }
 
-    function get_directory($plugin) {
+    /**
+     * Returns directory name of plugin
+     *
+     * @param string $plugin name of plugin
+     * @return string name of directory
+     */
+    public function get_directory($plugin) {
         return $plugin;
     }
 
+    /**
+     * Returns cascade of the config files
+     *
+     * @return array with arrays of plugin configs
+     */
+    public function getCascade() {
+        return $this->plugin_cascade;
+    }
+
     protected function _populateMasterList() {
         global $conf;
 
@@ -169,6 +204,13 @@ class Doku_Plugin_Controller {
         }
     }
 
+    /**
+     * Includes the plugin config $files
+     * and returns the entries of the $plugins array set in these files
+     *
+     * @param array $files list of files to include, latter overrides previous
+     * @return array with entries of the $plugins arrays of the included files
+     */
     protected function checkRequire($files) {
         $plugins = array();
         foreach($files as $file) {
@@ -179,14 +221,15 @@ class Doku_Plugin_Controller {
         return $plugins;
     }
 
-    function getCascade() {
-        return $this->plugin_cascade;
-    }
-
     /**
      * Save the current list of plugins
+     *
+     * @param bool $forceSave;
+     *              false to save only when config changed
+     *              true to always save
+     * @return bool; true saving succeed, false saving failed
      */
-    function saveList($forceSave = false) {
+    protected function saveList($forceSave = false) {
         global $conf;
 
         if (empty($this->tmp_plugins)) return false;
@@ -216,9 +259,10 @@ class Doku_Plugin_Controller {
 
     /**
      * Rebuild the set of local plugins
+     *
      * @return array array of plugins to be saved in end($config_cascade['plugins']['local'])
      */
-    function rebuildLocal() {
+    protected function rebuildLocal() {
         //assign to local variable to avoid overwriting
         $backup = $this->tmp_plugins;
         //Can't do anything about protected one so rule them out completely
@@ -238,7 +282,7 @@ class Doku_Plugin_Controller {
      * Build the list of plugins and cascade
      * 
      */
-    function loadConfig() {
+    protected function loadConfig() {
         global $config_cascade;
         foreach(array('default','protected') as $type) {
             if(array_key_exists($type,$config_cascade['plugins']))
@@ -253,7 +297,18 @@ class Doku_Plugin_Controller {
         $this->tmp_plugins = array_merge($this->plugin_cascade['default'],$this->plugin_cascade['local'],$this->plugin_cascade['protected']);
     }
 
-    function _getListByType($type, $enabled) {
+    /**
+     * 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
+     *
+     * @return array of plugin components of requested type
+     */
+    protected function _getListByType($type, $enabled) {
         $master_list = $enabled ? array_keys(array_filter($this->tmp_plugins)) : array_keys(array_filter($this->tmp_plugins,array($this,'negate')));
 
         $plugins = array();
@@ -278,14 +333,29 @@ class Doku_Plugin_Controller {
         return $plugins;
     }
 
-    function _splitName($name) {
+    /**
+     * Split name in a plugin name and a component name
+     *
+     * @param string $name
+     * @return array with
+     *              - plugin name
+     *              - and component name when available, otherwise empty string
+     */
+    protected function _splitName($name) {
         if (array_search($name, array_keys($this->tmp_plugins)) === false) {
             return explode('_',$name,2);
         }
 
         return array($name,'');
     }
-    function negate($input) {
+
+    /**
+     * Returns inverse boolean value of the input
+     *
+     * @param mixed $input
+     * @return bool inversed boolean value of input
+     */
+    protected function negate($input) {
         return !(bool) $input;
     }
 }
diff --git a/inc/pluginutils.php b/inc/pluginutils.php
index 7c37d4f7f..894bbefb6 100644
--- a/inc/pluginutils.php
+++ b/inc/pluginutils.php
@@ -14,31 +14,92 @@ if(!defined('DOKU_PLUGIN_NAME_REGEX')) define('DOKU_PLUGIN_NAME_REGEX', '[a-zA-Z
 /**
  * Original plugin functions, remain for backwards compatibility
  */
+
+/**
+ * Return list of available plugins
+ *
+ * @param string $type type of plugins; empty string for all
+ * @param bool $all; true to retrieve all, false to retrieve only enabled plugins
+ * @return array with plugin names or plugin component names
+ */
 function plugin_list($type='',$all=false) {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->getList($type,$all);
 }
+
+/**
+ * Returns plugin object
+ * Returns only new instances of a plugin when $new is true or if plugin is not Singleton,
+ * otherwise an already loaded instance.
+ *
+ * @param  $type     string type of plugin to load
+ * @param  $name     string name of the plugin to load
+ * @param  $new      bool   true to return a new instance of the plugin, false to use an already loaded instance
+ * @param  $disabled bool   true to load even disabled plugins
+ * @return DokuWiki_Plugin|DokuWiki_Syntax_Plugin|null  the plugin object or null on failure
+ */
 function plugin_load($type,$name,$new=false,$disabled=false) {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->load($type,$name,$new,$disabled);
 }
+
+/**
+ * Whether plugin is disabled
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true disabled, false enabled
+ */
 function plugin_isdisabled($plugin) {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->isdisabled($plugin);
 }
+
+/**
+ * Enable the plugin
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true saving succeed, false saving failed
+ */
 function plugin_enable($plugin) {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->enable($plugin);
 }
+
+/**
+ * Disable the plugin
+ *
+ * @param string $plugin name of plugin
+ * @return bool; true saving succeed, false saving failed
+ */
 function plugin_disable($plugin) {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->disable($plugin);
 }
+
+/**
+ * Returns directory name of plugin
+ *
+ * @param string $plugin name of plugin
+ * @return string name of directory
+ */
 function plugin_directory($plugin) {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->get_directory($plugin);
 }
+
+/**
+ * Returns cascade of the config files
+ *
+ * @return array with arrays of plugin configs
+ */
 function plugin_getcascade() {
+    /** @var $plugin_controller Doku_Plugin_Controller */
     global $plugin_controller;
     return $plugin_controller->getCascade();
 }
diff --git a/inc/search.php b/inc/search.php
index 884aa7b23..cd36feeab 100644
--- a/inc/search.php
+++ b/inc/search.php
@@ -9,14 +9,15 @@
 if(!defined('DOKU_INC')) die('meh.');
 
 /**
- * recurse direcory
+ * Recurse directory
  *
  * This function recurses into a given base directory
  * and calls the supplied function for each file and directory
  *
- * @param   array ref $data The results of the search are stored here
+ * @param   array    &$data The results of the search are stored here
  * @param   string    $base Where to start the search
  * @param   callback  $func Callback (function name or array with object,method)
+ * @param   array     $opts option array will be given to the Callback
  * @param   string    $dir  Current directory beyond $base
  * @param   int       $lvl  Recursion Level
  * @param   mixed     $sort 'natural' to use natural order sorting (default); 'date' to sort by filemtime; leave empty to skip sorting.
@@ -68,12 +69,12 @@ function search(&$data,$base,$func,$opts,$dir='',$lvl=1,$sort='natural'){
  * decide if this directory should be traversed (true) or not (false)
  * The function has to accept the following parameters:
  *
- * &$data - Reference to the result data structure
- * $base  - Base usually $conf['datadir']
- * $file  - current file or directory relative to $base
- * $type  - Type either 'd' for directory or 'f' for file
- * $lvl   - Current recursion depht
- * $opts  - option array as given to search()
+ * array &$data  - Reference to the result data structure
+ * string $base  - Base usually $conf['datadir']
+ * string $file  - current file or directory relative to $base
+ * string $type  - Type either 'd' for directory or 'f' for file
+ * int    $lvl   - Current recursion depht
+ * array  $opts  - option array as given to search()
  *
  * return values for files are ignored
  *
@@ -334,6 +335,15 @@ function pathID($path,$keeptxt=false){
  * showhidden bool    show hidden files too
  * firsthead  bool    return first heading for pages
  *
+ * @param array &$data - Reference to the result data structure
+ * @param string $base  - Base usually $conf['datadir']
+ * @param string $file  - current file or directory relative to $base
+ * @param string $type  - Type either 'd' for directory or 'f' for file
+ * @param int    $lvl   - Current recursion depht
+ * @param array  $opts  - option array as given to search()
+ * @return bool if this directory should be traversed (true) or not (false)
+ *              return value is ignored for files
+ *
  * @author Andreas Gohr <gohr@cosmocode.de>
  */
 function search_universal(&$data,$base,$file,$type,$lvl,$opts){