Merge pull request #557 from splitbrain/cachetimeattr

Add  _time attribute to cache object and minor PHPDocs improvements

7 files changed, 139 insertions, 61 deletions

diff --git a/inc/EmailAddressValidator.php b/inc/EmailAddressValidator.php
index bb4ef0ca9..fd6f3275b 100644
--- a/inc/EmailAddressValidator.php
+++ b/inc/EmailAddressValidator.php
@@ -15,8 +15,8 @@ class EmailAddressValidator {
 
     /**
      * Check email address validity
-     * @param   strEmailAddress     Email address to be checked
-     * @return  True if email is valid, false if not
+     * @param  string $strEmailAddress     Email address to be checked
+     * @return bool True if email is valid, false if not
      */
     public function check_email_address($strEmailAddress) {
 
@@ -82,8 +82,8 @@ class EmailAddressValidator {
 
     /**
      * Checks email section before "@" symbol for validity
-     * @param   strLocalPortion     Text to be checked
-     * @return  True if local portion is valid, false if not
+     * @param string  $strLocalPortion     Text to be checked
+     * @return bool True if local portion is valid, false if not
      */
     protected function check_local_portion($strLocalPortion) {
         // Local portion can only be from 1 to 64 characters, inclusive.
@@ -113,8 +113,8 @@ class EmailAddressValidator {
 
     /**
      * Checks email section after "@" symbol for validity
-     * @param   strDomainPortion     Text to be checked
-     * @return  True if domain portion is valid, false if not
+     * @param  string $strDomainPortion     Text to be checked
+     * @return bool True if domain portion is valid, false if not
      */
     protected function check_domain_portion($strDomainPortion) {
         // Total domain can only be from 1 to 255 characters, inclusive
@@ -172,10 +172,10 @@ class EmailAddressValidator {
 
     /**
      * Check given text length is between defined bounds
-     * @param   strText     Text to be checked
-     * @param   intMinimum  Minimum acceptable length
-     * @param   intMaximum  Maximum acceptable length
-     * @return  True if string is within bounds (inclusive), false if not
+     * @param   string $strText     Text to be checked
+     * @param   int $intMinimum  Minimum acceptable length
+     * @param   int $intMaximum  Maximum acceptable length
+     * @return bool True if string is within bounds (inclusive), false if not
      */
     protected function check_text_length($strText, $intMinimum, $intMaximum) {
         // Minimum and maximum are both inclusive
diff --git a/inc/cache.php b/inc/cache.php
index 5eac94934..5f54a34a9 100644
--- a/inc/cache.php
+++ b/inc/cache.php
@@ -8,16 +8,24 @@
 
 if(!defined('DOKU_INC')) die('meh.');
 
+/**
+ * Generic handling of caching
+ */
 class cache {
-    var $key = '';          // primary identifier for this item
-    var $ext = '';          // file ext for cache data, secondary identifier for this item
-    var $cache = '';        // cache file name
-    var $depends = array(); // array containing cache dependency information,
+    public $key = '';          // primary identifier for this item
+    public $ext = '';          // file ext for cache data, secondary identifier for this item
+    public $cache = '';        // cache file name
+    public $depends = array(); // array containing cache dependency information,
     //   used by _useCache to determine cache validity
 
     var $_event = '';       // event to be triggered during useCache
+    var $_time;
 
-    function cache($key,$ext) {
+    /**
+     * @param string $key primary identifier
+     * @param string $ext file extension
+     */
+    public function cache($key,$ext) {
         $this->key = $key;
         $this->ext = $ext;
         $this->cache = getCacheName($key,$ext);
@@ -36,7 +44,7 @@ class cache {
      *
      * @return bool    true if cache can be used, false otherwise
      */
-    function useCache($depends=array()) {
+    public function useCache($depends=array()) {
         $this->depends = $depends;
         $this->_addDependencies();
 
@@ -59,7 +67,7 @@ class cache {
      *
      * @return bool               see useCache()
      */
-    function _useCache() {
+    protected function _useCache() {
 
         if (!empty($this->depends['purge'])) return false;              // purge requested?
         if (!($this->_time = @filemtime($this->cache))) return false;   // cache exists?
@@ -83,7 +91,7 @@ class cache {
      * it should not remove any existing dependencies and
      * it should only overwrite a dependency when the new value is more stringent than the old
      */
-    function _addDependencies() {
+    protected function _addDependencies() {
         global $INPUT;
         if ($INPUT->has('purge')) $this->depends['purge'] = true;   // purge requested
     }
@@ -94,7 +102,7 @@ class cache {
      * @param   bool   $clean   true to clean line endings, false to leave line endings alone
      * @return  string          cache contents
      */
-    function retrieveCache($clean=true) {
+    public function retrieveCache($clean=true) {
         return io_readFile($this->cache, $clean);
     }
 
@@ -104,14 +112,14 @@ class cache {
      * @param   string $data   the data to be cached
      * @return  bool           true on success, false otherwise
      */
-    function storeCache($data) {
+    public function storeCache($data) {
         return io_savefile($this->cache, $data);
     }
 
     /**
      * remove any cached data associated with this cache instance
      */
-    function removeCache() {
+    public function removeCache() {
         @unlink($this->cache);
     }
 
@@ -122,7 +130,7 @@ class cache {
      * @param    bool   $success   result of this cache use attempt
      * @return   bool              pass-thru $success value
      */
-    function _stats($success) {
+    protected function _stats($success) {
         global $conf;
         static $stats = null;
         static $file;
@@ -157,14 +165,23 @@ class cache {
     }
 }
 
+/**
+ * Parser caching
+ */
 class cache_parser extends cache {
 
-    var $file = '';       // source file for cache
-    var $mode = '';       // input mode (represents the processing the input file will undergo)
+    public $file = '';       // source file for cache
+    public $mode = '';       // input mode (represents the processing the input file will undergo)
 
     var $_event = 'PARSER_CACHE_USE';
 
-    function cache_parser($id, $file, $mode) {
+    /**
+     *
+     * @param string $id page id
+     * @param string $file source file for cache
+     * @param string $mode input mode
+     */
+    public function cache_parser($id, $file, $mode) {
         if ($id) $this->page = $id;
         $this->file = $file;
         $this->mode = $mode;
@@ -172,24 +189,29 @@ class cache_parser extends cache {
         parent::cache($file.$_SERVER['HTTP_HOST'].$_SERVER['SERVER_PORT'],'.'.$mode);
     }
 
-    function _useCache() {
+    /**
+     * method contains cache use decision logic
+     *
+     * @return bool               see useCache()
+     */
+    protected function _useCache() {
 
         if (!@file_exists($this->file)) return false;                   // source exists?
         return parent::_useCache();
     }
 
-    function _addDependencies() {
-        global $conf, $config_cascade;
+    protected function _addDependencies() {
+        global $conf;
 
         $this->depends['age'] = isset($this->depends['age']) ?
             min($this->depends['age'],$conf['cachetime']) : $conf['cachetime'];
 
         // parser cache file dependencies ...
-        $files = array($this->file,                                     // ... source
+        $files = array($this->file,                              // ... source
                 DOKU_INC.'inc/parser/parser.php',                // ... parser
                 DOKU_INC.'inc/parser/handler.php',               // ... handler
                 );
-        $files = array_merge($files, getConfigFiles('main'));           // ... wiki settings
+        $files = array_merge($files, getConfigFiles('main'));    // ... wiki settings
 
         $this->depends['files'] = !empty($this->depends['files']) ? array_merge($files, $this->depends['files']) : $files;
         parent::_addDependencies();
@@ -197,8 +219,17 @@ class cache_parser extends cache {
 
 }
 
+/**
+ * Caching of data of renderer
+ */
 class cache_renderer extends cache_parser {
-    function _useCache() {
+
+    /**
+     * method contains cache use decision logic
+     *
+     * @return bool               see useCache()
+     */
+    protected function _useCache() {
         global $conf;
 
         if (!parent::_useCache()) return false;
@@ -231,7 +262,7 @@ class cache_renderer extends cache_parser {
         return true;
     }
 
-    function _addDependencies() {
+    protected function _addDependencies() {
 
         // renderer cache file dependencies ...
         $files = array(
@@ -253,18 +284,37 @@ class cache_renderer extends cache_parser {
     }
 }
 
+/**
+ * Caching of parser instructions
+ */
 class cache_instructions extends cache_parser {
 
-    function cache_instructions($id, $file) {
+    /**
+     * @param string $id page id
+     * @param string $file source file for cache
+     */
+    public function cache_instructions($id, $file) {
         parent::cache_parser($id, $file, 'i');
     }
 
-    function retrieveCache($clean=true) {
+    /**
+     * retrieve the cached data
+     *
+     * @param   bool   $clean   true to clean line endings, false to leave line endings alone
+     * @return  string          cache contents
+     */
+    public function retrieveCache($clean=true) {
         $contents = io_readFile($this->cache, false);
         return !empty($contents) ? unserialize($contents) : array();
     }
 
-    function storeCache($instructions) {
+    /**
+     * cache $instructions
+     *
+     * @param   string $instructions  the instruction to be cached
+     * @return  bool                  true on success, false otherwise
+     */
+    public function storeCache($instructions) {
         return io_savefile($this->cache,serialize($instructions));
     }
 }
diff --git a/inc/common.php b/inc/common.php
index bbc0a6e68..9a53ee526 100644
--- a/inc/common.php
+++ b/inc/common.php
@@ -1141,7 +1141,6 @@ function saveWikiText($id, $text, $summary, $minor = false) {
  * @author Andreas Gohr <andi@splitbrain.org>
  */
 function saveOldRevision($id) {
-    global $conf;
     $oldf = wikiFN($id);
     if(!@file_exists($oldf)) return '';
     $date = filemtime($oldf);
@@ -1231,8 +1230,9 @@ 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>
  * @author      Aidan Lister <aidan@php.net>
  * @version     1.0.0
@@ -1363,12 +1363,16 @@ function php_to_byte($v) {
     $l   = substr($v, -1);
     $ret = substr($v, 0, -1);
     switch(strtoupper($l)) {
+        /** @noinspection PhpMissingBreakStatementInspection */
         case 'P':
             $ret *= 1024;
+        /** @noinspection PhpMissingBreakStatementInspection */
         case 'T':
             $ret *= 1024;
+        /** @noinspection PhpMissingBreakStatementInspection */
         case 'G':
             $ret *= 1024;
+        /** @noinspection PhpMissingBreakStatementInspection */
         case 'M':
             $ret *= 1024;
         case 'K':
diff --git a/inc/events.php b/inc/events.php
index 58ba4d5e4..7f9824f60 100644
--- a/inc/events.php
+++ b/inc/events.php
@@ -8,6 +8,9 @@
 
 if(!defined('DOKU_INC')) die('meh.');
 
+/**
+ * The event
+ */
 class Doku_Event {
 
     // public properties
@@ -32,6 +35,9 @@ class Doku_Event {
 
     }
 
+    /**
+     * @return string
+     */
     function __toString() {
         return $this->name;
     }
@@ -51,7 +57,8 @@ class Doku_Event {
      *    $evt->advise_after();
      *    unset($evt);
      *
-     * @return  results of processing the event, usually $this->_default
+     * @param bool $enablePreventDefault
+     * @return bool results of processing the event, usually $this->_default
      */
     function advise_before($enablePreventDefault=true) {
         global $EVENT_HANDLER;
@@ -77,7 +84,9 @@ class Doku_Event {
      *   $this->_default, all of which may have been modified by the event handlers.
      * - advise all registered (<event>_AFTER) handlers that the event has taken place
      *
-     * @return  $event->results
+     * @param null|callable $action
+     * @param bool $enablePrevent
+     * @return  mixed $event->results
      *          the value set by any <event>_before or <event> handlers if the default action is prevented
      *          or the results of the default action (as modified by <event>_after handlers)
      *          or NULL no action took place and no handler modified the value
@@ -116,6 +125,9 @@ class Doku_Event {
     function preventDefault() { $this->_default = false;  }
 }
 
+/**
+ * Controls the registration and execution of all events,
+ */
 class Doku_Event_Handler {
 
     // public properties:  none
@@ -132,6 +144,7 @@ class Doku_Event_Handler {
     function Doku_Event_Handler() {
 
         // load action plugins
+        /** @var DokuWiki_Action_Plugin $plugin */
         $plugin = null;
         $pluginlist = plugin_list('action');
 
@@ -147,12 +160,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  $obj     (obj)      object in whose scope method is to be executed,
+     * @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,
      *                             if NULL, method is assumed to be a globally available function
-     * @param  $method  (function) event handler function
-     * @param  $param   (mixed)    data passed to the event handler
-     * @param  $seq     (int)      sequence number for ordering hook execution (ascending)
+     * @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)
      */
     function register_hook($event, $advise, $obj, $method, $param=null, $seq=0) {
         $seq = (int)$seq;
@@ -164,6 +178,12 @@ class Doku_Event_Handler {
         }
     }
 
+    /**
+     * process the before/after event
+     *
+     * @param Doku_Event $event
+     * @param string     $advise BEFORE or AFTER
+     */
     function process_event($event,$advise='') {
 
         $evt_name = $event->name . ($advise ? '_'.$advise : '_BEFORE');
@@ -191,12 +211,12 @@ 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  $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
  *
- * @return (mixed)                        the event results value after all event processing is complete
+ * @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
  */
diff --git a/inc/form.php b/inc/form.php
index 312c42b60..610f50200 100644
--- a/inc/form.php
+++ b/inc/form.php
@@ -47,15 +47,11 @@ class Doku_Form {
      * with up to four parameters is deprecated, instead the first parameter
      * should be an array with parameters.
      *
-     * @param   mixed   $params  Parameters for the HTML form element; Using the
-     *                           deprecated calling convention this is the ID
-     *                           attribute of the form
-     * @param   string  $action  (optional, deprecated) submit URL, defaults to
-     *                                                  current page
-     * @param   string  $method  (optional, deprecated) 'POST' or 'GET', default
-     *                                                  is POST
-     * @param   string  $enctype (optional, deprecated) Encoding type of the
-     *                                                  data
+     * @param mixed       $params  Parameters for the HTML form element; Using the deprecated
+     *                             calling convention this is the ID attribute of the 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) {
@@ -230,7 +226,7 @@ class Doku_Form {
      * first (underflow) or last (overflow) element.
      *
      * @param   int     $pos    0-based index
-     * @return  arrayreference  pseudo-element
+     * @return  array reference  pseudo-element
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function &getElementAt($pos) {
diff --git a/inc/pageutils.php b/inc/pageutils.php
index c8d3cf4bb..9c2794387 100644
--- a/inc/pageutils.php
+++ b/inc/pageutils.php
@@ -94,6 +94,7 @@ function getID($param='id',$clean=true){
  * @author Andreas Gohr <andi@splitbrain.org>
  * @param  string  $raw_id    The pageid to clean
  * @param  boolean $ascii     Force ASCII
+ * @return string cleaned id
  */
 function cleanID($raw_id,$ascii=false){
     global $conf;
@@ -244,6 +245,7 @@ function page_exists($id,$rev='',$clean=true) {
  * @param  $rev     string   page revision, empty string for current
  * @param  $clean   bool     flag indicating that $raw_id should be cleaned.  Only set to false
  *                           when $id is guaranteed to have been cleaned already.
+ * @return string full path
  *
  * @author Andreas Gohr <andi@splitbrain.org>
  */
@@ -361,6 +363,7 @@ function mediaFN($id, $rev=''){
  *
  * @param  string $id  The id of the local file
  * @param  string $ext The file extension (usually txt)
+ * @return string full filepath to localized file
  * @author Andreas Gohr <andi@splitbrain.org>
  */
 function localeFN($id,$ext='txt'){
@@ -543,6 +546,11 @@ function isHiddenPage($id){
     return $data['hidden'];
 }
 
+/**
+ * callback checks if page is hidden
+ *
+ * @param array $data event data    see isHiddenPage()
+ */
 function _isHiddenPage(&$data) {
     global $conf;
     global $ACT;
diff --git a/inc/pluginutils.php b/inc/pluginutils.php
index 894bbefb6..911c4e5c0 100644
--- a/inc/pluginutils.php
+++ b/inc/pluginutils.php
@@ -37,7 +37,7 @@ function plugin_list($type='',$all=false) {
  * @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
+ * @return DokuWiki_Plugin|null  the plugin object or null on failure
  */
 function plugin_load($type,$name,$new=false,$disabled=false) {
     /** @var $plugin_controller Doku_Plugin_Controller */