add visibility keywords and PHPDocs for cache

inc/cache.php

@@ -9,16 +9,20 @@
 if(!defined('DOKU_INC')) die('meh.');
 
 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);
@@ -37,7 +41,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();
 
@@ -60,7 +64,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?
@@ -84,7 +88,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
     }
@@ -95,7 +99,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);
     }
 
@@ -105,14 +109,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);
     }
 
@@ -123,7 +127,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;
@@ -160,12 +164,18 @@ class cache {
 
 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;
@@ -173,24 +183,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();
@@ -199,7 +214,13 @@ class cache_parser extends cache {
 }
 
 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;
@@ -232,7 +253,7 @@ class cache_renderer extends cache_parser {
         return true;
     }
 
-    function _addDependencies() {
+    protected function _addDependencies() {
 
         // renderer cache file dependencies ...
         $files = array(
@@ -256,16 +277,32 @@ class cache_renderer extends cache_parser {
 
 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));
     }
 }