Merge pull request #3614 from cakephp/api-doc-comments-2

Api doc comments 2

lib/Cake/Cache/Cache.php

@@ -113,11 +113,11 @@ class Cache {
  * - `user` Used by Xcache. Username for XCache
  * - `password` Used by Xcache/Redis. Password for XCache/Redis
  *
- * @see app/Config/core.php for configuration settings
  * @param string $name Name of the configuration
  * @param array $settings Optional associative array of settings passed to the engine
  * @return array array(engine, settings) on success, false on failure
  * @throws CacheException
+ * @see app/Config/core.php for configuration settings
  */
 	public static function config($name = null, $settings = array()) {
 		if (is_array($name)) {
@@ -561,6 +561,7 @@ class Cache {
  *   the cache key is empty. Can be any callable type supported by your PHP.
  * @param string $config The cache configuration to use for this operation.
  *   Defaults to default.
+ * @return mixed The results of the callable or unserialized results.
  */
 	public static function remember($key, $callable, $config = 'default') {
 		$existing = self::read($key, $config);

lib/Cake/Cache/CacheEngine.php

@@ -130,7 +130,7 @@ abstract class CacheEngine {
  * to decide whether actually delete the keys or just simulate it to achieve
  * the same result.
  *
- * @param string $groups name of the group to be cleared
+ * @param string $group name of the group to be cleared
  * @return boolean
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/ApcEngine.php

@@ -173,6 +173,7 @@ class ApcEngine extends CacheEngine {
  * Increments the group value to simulate deletion of all keys under a group
  * old values will remain in storage until they expire.
  *
+ * @param string $group The group to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/FileEngine.php

@@ -303,8 +303,8 @@ class FileEngine extends CacheEngine {
 /**
  * Not implemented
  *
- * @param string $key
+ * @param string $key The key to decrement
- * @param integer $offset
+ * @param integer $offset The number to offset
  * @return void
  * @throws CacheException
  */
@@ -315,8 +315,8 @@ class FileEngine extends CacheEngine {
 /**
  * Not implemented
  *
- * @param string $key
+ * @param string $key The key to decrement
- * @param integer $offset
+ * @param integer $offset The number to offset
  * @return void
  * @throws CacheException
  */
@@ -405,6 +405,7 @@ class FileEngine extends CacheEngine {
 /**
  * Recursively deletes all files under any directory named as $group
  *
+ * @param string $group The group to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/MemcacheEngine.php

@@ -199,7 +199,8 @@ class MemcacheEngine extends CacheEngine {
 /**
  * Delete all keys from the cache
  *
- * @param boolean $check
+ * @param boolean $check If true no deletes will occur and instead CakePHP will rely
+ *   on key TTL values.
  * @return boolean True if the cache was successfully cleared, false otherwise
  */
 	public function clear($check) {
@@ -282,6 +283,7 @@ class MemcacheEngine extends CacheEngine {
  * Increments the group value to simulate deletion of all keys under a group
  * old values will remain in storage until they expire.
  *
+ * @param string $group The group to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/MemcachedEngine.php

@@ -136,6 +136,7 @@ class MemcachedEngine extends CacheEngine {
  * Settings the memcached instance
  *
  * @throws CacheException when the Memcached extension is not built with the desired serializer engine
+ * @return void
  */
 	protected function _setOptions() {
 		$this->_Memcached->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);
@@ -257,7 +258,8 @@ class MemcachedEngine extends CacheEngine {
 /**
  * Delete all keys from the cache
  *
- * @param boolean $check
+ * @param boolean $check If true no deletes will occur and instead CakePHP will rely
+ *   on key TTL values.
  * @return boolean True if the cache was successfully cleared, false otherwise
  */
 	public function clear($check) {
@@ -314,6 +316,7 @@ class MemcachedEngine extends CacheEngine {
  * Increments the group value to simulate deletion of all keys under a group
  * old values will remain in storage until they expire.
  *
+ * @param string $group The group to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/RedisEngine.php

@@ -175,7 +175,8 @@ class RedisEngine extends CacheEngine {
 /**
  * Delete all keys from the cache
  *
- * @param boolean $check
+ * @param boolean $check Whether or not expiration keys should be checked. If
+ *   true, no keys will be removed as cache will rely on redis TTL's.
  * @return boolean True if the cache was successfully cleared, false otherwise
  */
 	public function clear($check) {
@@ -212,6 +213,7 @@ class RedisEngine extends CacheEngine {
  * Increments the group value to simulate deletion of all keys under a group
  * old values will remain in storage until they expire.
  *
+ * @param string $group The group name to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/WincacheEngine.php

@@ -179,6 +179,7 @@ class WincacheEngine extends CacheEngine {
  * Increments the group value to simulate deletion of all keys under a group
  * old values will remain in storage until they expire.
  *
+ * @param string $group The group to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Cache/Engine/XcacheEngine.php

@@ -126,7 +126,8 @@ class XcacheEngine extends CacheEngine {
 /**
  * Delete all keys from the cache
  *
- * @param boolean $check
+ * @param boolean $check If true no deletes will occur and instead CakePHP will rely
+ *   on key TTL values.
  * @return boolean True if the cache was successfully cleared, false otherwise
  */
 	public function clear($check) {
@@ -163,6 +164,7 @@ class XcacheEngine extends CacheEngine {
  * Increments the group value to simulate deletion of all keys under a group
  * old values will remain in storage until they expire.
  *
+ * @param string $group The group to clear.
  * @return boolean success
  */
 	public function clearGroup($group) {

lib/Cake/Error/ErrorHandler.php

@@ -102,7 +102,7 @@ class ErrorHandler {
  * This will either use custom exception renderer class if configured,
  * or use the default ExceptionRenderer.
  *
- * @param Exception $exception
+ * @param Exception $exception The exception to render.
  * @return void
  * @see http://php.net/manual/en/function.set-exception-handler.php
  */
@@ -132,6 +132,7 @@ class ErrorHandler {
 
 /**
  * Generates a formatted error message
+ *
  * @param Exception $exception Exception instance
  * @return string Formatted message
  */
@@ -159,8 +160,8 @@ class ErrorHandler {
 /**
  * Handles exception logging
  *
- * @param Exception $exception
+ * @param Exception $exception The exception to render.
- * @param array $config
+ * @param array $config An array of configuration for logging.
  * @return boolean
  */
 	protected static function _log(Exception $exception, $config) {

lib/Cake/Error/ExceptionRenderer.php

@@ -180,7 +180,7 @@ class ExceptionRenderer {
 /**
  * Generic handler for the internal framework errors CakePHP can generate.
  *
- * @param CakeException $error
+ * @param CakeException $error The exception to render.
  * @return void
  */
 	protected function _cakeError(CakeException $error) {
@@ -202,7 +202,7 @@ class ExceptionRenderer {
 /**
  * Convenience method to display a 400 series page.
  *
- * @param Exception $error
+ * @param Exception $error The exception to render.
  * @return void
  */
 	public function error400($error) {
@@ -225,7 +225,7 @@ class ExceptionRenderer {
 /**
  * Convenience method to display a 500 page.
  *
- * @param Exception $error
+ * @param Exception $error The exception to render.
  * @return void
  */
 	public function error500($error) {
@@ -249,7 +249,7 @@ class ExceptionRenderer {
 /**
  * Convenience method to display a PDOException.
  *
- * @param PDOException $error
+ * @param PDOException $error The exception to render.
  * @return void
  */
 	public function pdoError(PDOException $error) {

lib/Cake/Error/exceptions.php

@@ -34,9 +34,9 @@ class CakeBaseException extends RuntimeException {
 /**
  * Get/set the response header to be used
  *
- * @param string|array $header. An array of header strings or a single header string
+ * @param string|array $header An array of header strings or a single header string
- *	- an associative array of "header name" => "header value"
+ *  - an associative array of "header name" => "header value"
- *	- an array of string headers is also accepted
+ *  - an array of string headers is also accepted
  * @param string $value The header value.
  * @return array
  * @see CakeResponse::header()
@@ -378,6 +378,12 @@ class MissingConnectionException extends CakeException {
 
 	protected $_messageTemplate = 'Database connection "%s" is missing, or could not be created.';
 
+/**
+ * Constructor
+ *
+ * @param string|array $message The error message.
+ * @param int $code The error code.
+ */
 	public function __construct($message, $code = 500) {
 		if (is_array($message)) {
 			$message += array('enabled' => true);
@@ -587,10 +593,10 @@ class FatalErrorException extends CakeException {
 /**
  * Constructor
  *
- * @param string $message
+ * @param string $message The error message.
- * @param integer $code
+ * @param integer $code The error code.
- * @param string $file
+ * @param string $file The file the error occurred in.
- * @param integer $line
+ * @param integer $line The line the error occurred on.
  */
 	public function __construct($message, $code = 500, $file = null, $line = null) {
 		parent::__construct($message, $code);

lib/Cake/basics.php

@@ -125,7 +125,7 @@ if (!function_exists('sortByKey')) {
 /**
  * Sorts given $array by key $sortBy.
  *
- * @param array $array Array to sort
+ * @param array &$array Array to sort
  * @param string $sortBy Sort by this key
  * @param string $order Sort order asc/desc (ascending or descending).
  * @param integer $type Type of sorting to perform
@@ -235,10 +235,10 @@ if (!function_exists('pr')) {
  * In terminals this will act the same as using print_r() directly, when not run on cli
  * print_r() will wrap <PRE> tags around the output of given array. Similar to debug().
  *
- * @see debug()
  * @param mixed $var Variable to print out
  * @return void
  * @link http://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#pr
+ * @see debug()
  */
 	function pr($var) {
 		if (Configure::read('debug') > 0) {
@@ -254,10 +254,8 @@ if (!function_exists('am')) {
 /**
  * Merge a group of arrays
  *
- * @param array First array
+ * Accepts variable arguments. Each argument will be converted into an array and then merged.
- * @param array Second array
+ *
- * @param array Third array
- * @param array Etc...
  * @return array All array parameters merged into one
  * @link http://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#am
  */
@@ -840,7 +838,7 @@ if (!function_exists('convertSlash')) {
 /**
  * Convert forward slashes to underscores and removes first and last underscores in a string
  *
- * @param string String to convert
+ * @param string $string String to convert
  * @return string with underscore remove from start and end of string
  * @link http://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#convertSlash
  */