Adding comments for cache

git-svn-id: https://svn.cakephp.org/repo/branches/1.2.x.x@5128 3807eeeb-6ff5-0310-8944-8be069107fe0

cake/libs/cache.php

@@ -49,12 +49,13 @@ if(!defined('CACHE_GC_PROBABILITY')) {
 class Cache extends Object {
 /**
  * Cache engine to use
+ *
  * @var object
+ * @access private
  */
 	var $_Engine = null;
 /**
- * Enter description here...
+ * Create cache.
- *
  */
 	function __construct() {
 	}
@@ -62,6 +63,7 @@ class Cache extends Object {
  * Returns a singleton instance
  *
  * @return object
+ * @access public
  */
 	function &getInstance() {
 		static $instance = array();
@@ -72,8 +74,10 @@ class Cache extends Object {
 	}
 /**
  * Tries to find and include a file for a cache engine
- * @param $name
+ *
+ * @param $name	Name of the engine (without 'Engine')
  * @return boolean
+ * @access private
  */
 	function _includeEngine($name) {
 		if (class_exists($name.'Engine')) {
@@ -98,6 +102,7 @@ class Cache extends Object {
  * @param string $name Name of the engine (without 'Engine')
  * @param array $parmas Optional associative array of parameters passed to the engine
  * @return boolean True on success, false on failure
+ * @access public
  */
 	function engine($name = 'File', $params = array()) {
 		if(defined('DISABLE_CACHE')) {
@@ -127,6 +132,7 @@ class Cache extends Object {
  * @param mixed $value Data to be cached - anything except a resource
  * @param mixed $duration Optional - how long to cache the data, either in seconds or a string that can be parsed by the strtotime() function
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, $value, $duration = CACHE_DEFAULT_DURATION) {
 		if (defined('DISABLE_CACHE')) {
@@ -158,6 +164,7 @@ class Cache extends Object {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		if(defined('DISABLE_CACHE')) {
@@ -181,6 +188,7 @@ class Cache extends Object {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 		if(defined('DISABLE_CACHE')) {
@@ -202,6 +210,7 @@ class Cache extends Object {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear() {
 		if(defined('DISABLE_CACHE')) {
@@ -218,6 +227,7 @@ class Cache extends Object {
  * Check if Cache has initialized a working storage engine
  *
  * @return boolean
+ * @access public
  */
 	function isInitialized() {
 		if(defined('DISABLE_CACHE')) {
@@ -227,6 +237,12 @@ class Cache extends Object {
 		return isset($_this->_Engine);
 	}
 
+/**
+ * Return the settings for current cache engine
+ *
+ * @return array list of settings for this engine
+ * @access public
+ */
 	function settings() {
 		$_this =& Cache::getInstance();
 		if(!is_null($_this->_Engine)) {
@@ -248,6 +264,7 @@ class CacheEngine extends Object {
  *
  * @param array $params Associative array of parameters for the engine
  * @return boolean True if the engine has been succesfully initialized, false if not
+ * @access public
  */
 	function init($params) {
 	}
@@ -255,6 +272,8 @@ class CacheEngine extends Object {
  * Garbage collection
  *
  * Permanently remove all expired and deleted data
+ *
+ * @access public
  */
 	function gc() {
 	}
@@ -265,6 +284,7 @@ class CacheEngine extends Object {
  * @param mixed $value Data to be cached
  * @param mixed $duration How long to cache the data, in seconds
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, &$value, $duration = CACHE_DEFAULT_DURATION) {
 		trigger_error(sprintf(__('Method write() not implemented in %s', true), get_class($this)), E_USER_ERROR);
@@ -274,6 +294,7 @@ class CacheEngine extends Object {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		trigger_error(sprintf(__('Method read() not implemented in %s', true), get_class($this)), E_USER_ERROR);
@@ -283,6 +304,7 @@ class CacheEngine extends Object {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 	}
@@ -290,6 +312,7 @@ class CacheEngine extends Object {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear() {
 	}
@@ -297,6 +320,7 @@ class CacheEngine extends Object {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function settings() {
 		trigger_error(sprintf(__('Method settings() not implemented in %s', true), get_class($this)), E_USER_ERROR);

cake/libs/cache/apc.php

@@ -39,6 +39,7 @@ class APCEngine extends CacheEngine {
  *
  * @param array $params	Associative array of parameters for the engine
  * @return boolean	True if the engine has been succesfully initialized, false if not
+ * @access public
  */
 	function init(&$params) {
 		return function_exists('apc_cache_info');
@@ -50,6 +51,7 @@ class APCEngine extends CacheEngine {
  * @param mixed $value Data to be cached
  * @param int $duration How long to cache the data, in seconds
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, &$value, $duration = CACHE_DEFAULT_DURATION) {
 		return apc_store($key, $value, $duration);
@@ -59,6 +61,7 @@ class APCEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		return apc_fetch($key);
@@ -68,6 +71,7 @@ class APCEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 		return apc_delete($key);
@@ -76,6 +80,7 @@ class APCEngine extends CacheEngine {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear() {
 		return apc_clear_cache('user');
@@ -84,6 +89,7 @@ class APCEngine extends CacheEngine {
  * Return the settings for this cache engine
  *
  * @return array list of settings for this engine
+ * @access public
  */
 	function settings() {
 		return array('class' => get_class($this));

cake/libs/cache/file.php

@@ -44,18 +44,21 @@ class FileEngine extends CacheEngine {
  * Cache directory
  *
  * @var string
+ * @access private
  */
 	var $_dir = '';
 /**
  * Cache filename prefix
  *
  * @var string
+ * @access private
  */
 	var $_prefix = '';
 /**
  * Use locking
  *
  * @var boolean
+ * @access private
  */
 	var $_lock = false;
 /**
@@ -65,6 +68,7 @@ class FileEngine extends CacheEngine {
  *
  * @param array $params Associative array of parameters for the engine
  * @return boolean True if the engine has been succesfully initialized, false if not
+ * @access public
  */
 	function init($params) {
 		$dir = CACHE;
@@ -92,6 +96,7 @@ class FileEngine extends CacheEngine {
  * Permanently remove all expired and deleted data
  *
  * @return boolean True if garbage collection was succesful, false on failure
+ * @access public
  */
 	function gc() {
 		return $this->clear(true);
@@ -103,6 +108,7 @@ class FileEngine extends CacheEngine {
  * @param mixed $value Data to be cached
  * @param mixed $duration How long to cache the data, in seconds
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, &$value, $duration = CACHE_DEFAULT_DURATION) {
 		$serialized = serialize($value);
@@ -118,6 +124,7 @@ class FileEngine extends CacheEngine {
  *
  * @param string $key The key
  * @return string Absolute cache filename for the given key
+ * @access private
  */
 	function _getFilename($key) {
 		return $this->_dir . $this->_prefix . $this->base64url_encode($key);
@@ -129,6 +136,7 @@ class FileEngine extends CacheEngine {
  * @param string $value
  * @param integer $expires
  * @return boolean True on success, false on failure
+ * @access private
  */
 	function _writeCache(&$filename, &$value, &$expires) {
 		$contents = $expires."\n".$value."\n";
@@ -139,6 +147,7 @@ class FileEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		$filename = $this->_getFilename($key);
@@ -175,6 +184,7 @@ class FileEngine extends CacheEngine {
  *
  * @param string $filename
  * @return mixed Expiration timestamp, or false on failure
+ * @access private
  */
 	function _getExpiry($filename) {
 		$fp = fopen($filename, 'r');
@@ -195,6 +205,7 @@ class FileEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 		$filename = $this->_getFilename($key);
@@ -205,6 +216,7 @@ class FileEngine extends CacheEngine {
  *
  * @param boolean $checkExpiry Optional - only delete expired cache items
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear($checkExpiry = false) {
 		$dir = dir($this->_dir);
@@ -241,6 +253,7 @@ class FileEngine extends CacheEngine {
  * Return the settings for this cache engine
  *
  * @return array list of settings for this engine
+ * @access public
  */
 	function settings() {
 		$lock = 'false';
@@ -257,6 +270,7 @@ class FileEngine extends CacheEngine {
  *
  * @param string $str String to encode
  * @return string Encoded version of the string
+ * @access public
  */
 	function base64url_encode($str) {
 		return strtr(base64_encode($str), '+/', '-_');

cake/libs/cache/memcache.php

@@ -32,7 +32,19 @@
  * @subpackage	cake.cake.libs.cache
  */
 class MemcacheEngine extends CacheEngine {
+/**
+ * Memcache wrapper.
+ *
+ * @var object
+ * @access private
+ */
 	var $__Memcache = null;
+/**
+ * Memcache compress status.
+ *
+ * @var int
+ * @access private
+ */
 	var $_compress = 0;
 /**
  * Set up the cache engine
@@ -41,6 +53,7 @@ class MemcacheEngine extends CacheEngine {
  *
  * @param array $params Associative array of parameters for the engine
  * @return boolean True if the engine has been succesfully initialized, false if not
+ * @access public
  */
 	function init(&$params) {
 		if(!class_exists('Memcache')) {
@@ -80,6 +93,7 @@ class MemcacheEngine extends CacheEngine {
  * @param mixed $value Data to be cached
  * @param int $duration How long to cache the data, in seconds
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, &$value, $duration = CACHE_DEFAULT_DURATION) {
 		return $this->__Memcache->set($key, $value, $this->_compress, $duration);
@@ -89,6 +103,7 @@ class MemcacheEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		return $this->__Memcache->get($key);
@@ -98,6 +113,7 @@ class MemcacheEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 		return $this->__Memcache->delete($key);
@@ -106,6 +122,7 @@ class MemcacheEngine extends CacheEngine {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear() {
 		return $this->__Memcache->flush();
@@ -114,6 +131,7 @@ class MemcacheEngine extends CacheEngine {
  * Return the settings for this cache engine
  *
  * @return array list of settings for this engine
+ * @access public
  */
 	function settings() {
 		return array('class' => get_class($this),

cake/libs/cache/model.php

@@ -33,8 +33,27 @@
  * @subpackage	cake.cake.libs.cache
  */
 class ModelEngine extends CacheEngine {
+/**
+ * Model instance.
+ *
+ * @var object
+ * @access private
+ */
 	var $_Model = null;
+/**
+ * Fields that holds data.
+ *
+ * @var string
+ * @access private
+ */
 	var $_dataField = '';
+/**
+ * Field that holds expiration information.
+ *
+ * @var string
+ * @access private
+ */
+
 	var $_expiryField = '';
 /**
  * Set up the cache engine
@@ -62,6 +81,8 @@ class ModelEngine extends CacheEngine {
  * Garbage collection
  *
  * Permanently remove all expired and deleted data
+ *
+ * @access public
  */
 	function gc() {
 		return $this->_Model->deleteAll(array($this->_expiryField => '<= '.time()));
@@ -73,6 +94,7 @@ class ModelEngine extends CacheEngine {
  * @param mixed $value Data to be cached
  * @param mixed $duration How long to cache the data, in seconds
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, &$value, $duration = CACHE_DEFAULT_DURATION) {
 		$serialized = serialize($value);
@@ -95,6 +117,7 @@ class ModelEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		$val = $this->_Model->field($this->_expiryField, array($this->_Model->primaryKey => $key, $this->_expiryField => '> '.time()));
@@ -105,6 +128,7 @@ class ModelEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 		return $this->_Model->del($key);
@@ -113,6 +137,7 @@ class ModelEngine extends CacheEngine {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear() {
 		return $this->_Model->deleteAll(null);
@@ -121,6 +146,7 @@ class ModelEngine extends CacheEngine {
  * Return the settings for this cache engine
  *
  * @return array list of settings for this engine
+ * @access public
  */
 	function settings() {
 		$class = null;

cake/libs/cache/xcache.php

@@ -36,12 +36,14 @@ class XcacheEngine extends CacheEngine {
  * Admin username (xcache.admin.user)
  *
  * @var string
+ * @access private
  */
 	var $_php_auth_user = '';
 /**
  * Plaintext password for basic auth (xcache.admin.pass)
  *
  * @var string
+ * @access private
  */
 	var $_php_auth_pw = '';
 /**
@@ -51,6 +53,7 @@ class XcacheEngine extends CacheEngine {
  *
  * @param array $params	Associative array of parameters for the engine
  * @return boolean	True if the engine has been succesfully initialized, false if not
+ * @access public
  */
 	function init($params) {
 		$this->_php_auth_user = $params['user'];
@@ -64,6 +67,7 @@ class XcacheEngine extends CacheEngine {
  * @param mixed $value Data to be cached
  * @param int $duration How long to cache the data, in seconds
  * @return boolean True if the data was succesfully cached, false on failure
+ * @access public
  */
 	function write($key, &$value, $duration = CACHE_DEFAULT_DURATION) {
 		return xcache_set($key, $value, $duration);
@@ -73,6 +77,7 @@ class XcacheEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return mixed The cached data, or false if the data doesn't exist, has expired, or if there was an error fetching it
+ * @access public
  */
 	function read($key) {
 		if(xcache_isset($key)) {
@@ -85,6 +90,7 @@ class XcacheEngine extends CacheEngine {
  *
  * @param string $key Identifier for the data
  * @return boolean True if the value was succesfully deleted, false if it didn't exist or couldn't be removed
+ * @access public
  */
 	function delete($key) {
 		return xcache_unset($key);
@@ -93,6 +99,7 @@ class XcacheEngine extends CacheEngine {
  * Delete all values from the cache
  *
  * @return boolean True if the cache was succesfully cleared, false otherwise
+ * @access public
  */
 	function clear() {
 		$result = true;
@@ -111,6 +118,7 @@ class XcacheEngine extends CacheEngine {
  * Return the settings for this cache engine
  *
  * @return array list of settings for this engine
+ * @access public
  */
 	function settings() {
 		return array('class' => get_class($this));
@@ -120,6 +128,9 @@ class XcacheEngine extends CacheEngine {
  *
  * This has to be done because xcache_clear_cache() needs pass Basic Auth
  * (see xcache.admin configuration settings)
+ *
+ * @param boolean	Revert changes
+ * @access private
  */
 	function _phpAuth($reverse = false) {
 		static $backup = array();