improve visibility and PHPdocs of plugin controller

1 files changed, 93 insertions, 23 deletions

diff --git a/inc/plugincontroller.class.php b/inc/plugincontroller.class.php
index c825870cd..cd1eefded 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  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;
     }
 }