Updating doc blocks to improve readability in API.

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

cake/libs/cache.php

@@ -221,7 +221,7 @@ function gc() {
  * @param string $key Identifier for the data
  * @param mixed $value Data to be cached - anything except a resource
  * @param mixed $config Optional - string configuration name, a duration for expiration,
- *				or array('config' => 'string configuration name', 'duration' => 'duration for expiration')
+ *   or array('config' => 'string configuration name', 'duration' => 'duration for expiration')
  * @return boolean True if the data was successfully cached, false on failure
  * @access public
  * @static

cake/libs/class_registry.php

@@ -72,20 +72,26 @@ function &getInstance() {
 /**
  * Loads a class, registers the object in the registry and returns instance of the object.
  *
- * @param mixed $class as a string or a single key => value array instance will be created,
- * 	stored in the registry and returned.
- *   Required: array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass');
- *   Model Classes can accept optional array('id' => $id, 'table' => $table, 'ds' => $ds, 'alias' => $alias);
+ * Examples
+ * Simple Use: Get a Post model instance ```ClassRegistry::init('Post');```
+ * 
+ * Exapanded: ```array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass');```
+ * 
+ * Model Classes can accept optional ```array('id' => $id, 'table' => $table, 'ds' => $ds, 'alias' => $alias);```
+ * 
  * When $class is a numeric keyed array, multiple class instances will be stored in the registry,
- *   no instance of the object will be returned
- *   array(
- *  	array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass'),
- *  	array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass'),
- *  	array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass')
- *  );
- *
+ *  no instance of the object will be returned
+ * {{{
+ * array(
+ *		array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass'),
+ *		array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass'),
+ *		array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass')
+ * );
+ * }}}
+ * @param mixed $class as a string or a single key => value array instance will be created,
+ *  stored in the registry and returned.
  * @param string $type TypeOfClass
- * @return object intance of ClassName
+ * @return object instance of ClassName
  * @access public
  * @static
  */

cake/libs/configure.php

@@ -246,19 +246,22 @@ function __list($path, $suffix = false, $extension = false) {
 /**
  * Used to store a dynamic variable in the Configure instance.
  *
- * Usage
+ * Usage:
+ * {{{
  * Configure::write('One.key1', 'value of the Configure::One[key1]');
  * Configure::write(array('One.key1' => 'value of the Configure::One[key1]'));
  * Configure::write('One', array(
  *     'key1' => 'value of the Configure::One[key1]',
  *     'key2' => 'value of the Configure::One[key2]'
  * );
+ * 
  * Configure::write(array(
  *     'One.key1' => 'value of the Configure::One[key1]',
  *     'One.key2' => 'value of the Configure::One[key2]'
  * ));
+ * }}}
  *
- * @link          http://book.cakephp.org/view/412/write
+ * @link http://book.cakephp.org/view/412/write
  * @param array $config Name of var to write
  * @param mixed $value Value to set for var
  * @return void

cake/libs/controller/controller.php

@@ -321,7 +321,6 @@ function __construct() {
 		foreach ($parentMethods as $key => $value) {
 			$parentMethods[$key] = strtolower($value);
 		}
-
 		$this->methods = array_diff($childMethods, $parentMethods);
 		parent::__construct();
 	}
@@ -619,7 +618,7 @@ function header($status) {
  *
  * @param mixed $one A string or an array of data.
  * @param mixed $two Value in case $one is a string (which then works as the key).
- * 				Unused if $one is an associative array, otherwise serves as the values to $one's keys.
+ *   Unused if $one is an associative array, otherwise serves as the values to $one's keys.
  * @return void
  * @access public
  * @link http://book.cakephp.org/view/427/set

cake/libs/file.php

@@ -375,11 +375,11 @@ function md5($maxsize = 5) {
 		return false;
 	}
 /**
-* Returns the full path of the File.
-*
-* @return string Full path to file
-* @access public
-*/
+ * Returns the full path of the File.
+ * 
+ * @return string Full path to file
+ * @access public
+ */
 	function pwd() {
 		if (is_null($this->path)) {
 			$this->path = $this->Folder->slashTerm($this->Folder->pwd()) . $this->name;

cake/libs/model/behavior.php

@@ -363,9 +363,9 @@ function disable($name) {
  * Gets the list of currently-enabled behaviors, or, the current status of a single behavior
  *
  * @param string $name Optional.  The name of the behavior to check the status of.  If omitted,
- *						returns an array of currently-enabled behaviors
+ *   returns an array of currently-enabled behaviors
  * @return mixed If $name is specified, returns the boolean status of the corresponding behavior.
- *               Otherwise, returns an array of all enabled behaviors.
+ *   Otherwise, returns an array of all enabled behaviors.
  * @access public
  */
 	function enabled($name = null) {
@@ -463,9 +463,9 @@ function methods() {
  * Gets the list of attached behaviors, or, whether the given behavior is attached
  *
  * @param string $name Optional.  The name of the behavior to check the status of.  If omitted,
- *						returns an array of currently-attached behaviors
+ *   returns an array of currently-attached behaviors
  * @return mixed If $name is specified, returns the boolean status of the corresponding behavior.
- *               Otherwise, returns an array of all attached behaviors.
+ *    Otherwise, returns an array of all attached behaviors.
  * @access public
  */
 	function attached($name = null) {

cake/libs/model/behaviors/containable.php

@@ -47,18 +47,18 @@ class ContainableBehavior extends ModelBehavior {
  */
 	var $runtime = array();
 /**
- * Initiate behavior for the model using specified settings. Available settings:
+ * Initiate behavior for the model using specified settings.
+ * 
+ * Available settings:
  *
  * - recursive: (boolean, optional) set to true to allow containable to automatically
- * 				determine the recursiveness level needed to fetch specified models,
- * 				and set the model recursiveness to this level. setting it to false
- * 				disables this feature. DEFAULTS TO: true
- *
- * - notices:	(boolean, optional) issues E_NOTICES for bindings referenced in a
- * 				containable call that are not valid. DEFAULTS TO: true
- *
+ *   determine the recursiveness level needed to fetch specified models,
+ *   and set the model recursiveness to this level. setting it to false
+ *   disables this feature. DEFAULTS TO: true
+ * - notices: (boolean, optional) issues E_NOTICES for bindings referenced in a
+ *   containable call that are not valid. DEFAULTS TO: true
  * - autoFields: (boolean, optional) auto-add needed fields to fetch requested
- * 				bindings. DEFAULTS TO: true
+ *   bindings. DEFAULTS TO: true
  *
  * @param object $Model Model using the behavior
  * @param array $settings Settings to override for model.

cake/libs/model/datasources/dbo/dbo_db2.php

@@ -513,8 +513,8 @@ function column($real) {
  * do not correspond to a particular model belong under array
  * key 0.
  *
- * 1.  Gets the column headers
- *
+ * 1. Gets the column headers
+ * {{{
  * Post.id
  * Post.title
  *
@@ -529,7 +529,7 @@ function column($real) {
  *          [0] => Post
  *          [1] => title
  *      )
- *
+ * }}}
  * @param unknown_type $results
  */
 	function resultSet(&$results, $sql = null) {

cake/libs/model/datasources/dbo_source.php

@@ -2219,7 +2219,7 @@ function index($model) {
  *
  * @param object $schema An instance of a subclass of CakeSchema
  * @param string $tableName Optional.  If specified only the table name given will be generated.
- *						Otherwise, all tables defined in the schema are generated.
+ *   Otherwise, all tables defined in the schema are generated.
  * @return string
  */
 	function createSchema($schema, $tableName = null) {
@@ -2276,7 +2276,7 @@ function alterSchema($compare, $table = null) {
  *
  * @param object $schema An instance of a subclass of CakeSchema
  * @param string $table Optional.  If specified only the table name given will be generated.
- *						Otherwise, all tables defined in the schema are generated.
+ *   Otherwise, all tables defined in the schema are generated.
  * @return string
  */
 	function dropSchema($schema, $table = null) {
@@ -2297,7 +2297,7 @@ function dropSchema($schema, $table = null) {
  * Generate a database-native column schema string
  *
  * @param array $column An array structured like the following: array('name'=>'value', 'type'=>'value'[, options]),
- *						where options can be 'default', 'length', or 'key'.
+ *   where options can be 'default', 'length', or 'key'.
  * @return string
  */
 	function buildColumn($column) {

cake/libs/model/schema.php

@@ -167,10 +167,12 @@ function load($options = array()) {
 /**
  * Reads database and creates schema tables
  *
+ * Options
+ * 
+ * - 'connection' - the db connection to use
+ * - 'name' - name of the schema
+ * - 'models' - a list of models to use, or false to ignore models
  * @param array $options schema object properties
- *		'connection' - the db connection to use
- *		'name' - name of the schema
- *		'models' - a list of models to use, or false to ignore models
  * @return array Array indexed by name and tables
  * @access public
  */

cake/libs/router.php

@@ -218,22 +218,22 @@ function connect($route, $default = array(), $params = array()) {
  *Specifies what named parameters CakePHP should be parsing. The most common setups are:
  *
  * Do not parse any named parameters:
- * 	Router::connectNamed(false);
+ * {{{ Router::connectNamed(false); }}}
  *
  * Parse only default parameters used for CakePHP's pagination:
- * 	Router::connectNamed(false, array('default' => true));
+ * {{{ Router::connectNamed(false, array('default' => true)); }}}
  *
  * Parse only the page parameter if its value is a number:
- * 	Router::connectNamed(array('page' => '[\d]+'), array('default' => false, 'greedy' => false));
+ * {{{ Router::connectNamed(array('page' => '[\d]+'), array('default' => false, 'greedy' => false)); }}}
  *
  * Parse only the page parameter no mater what.
- * 	Router::connectNamed(array('page'), array('default' => false, 'greedy' => false));
+ * {{{ Router::connectNamed(array('page'), array('default' => false, 'greedy' => false)); }}}
  *
  * Parse only the page parameter if the current action is 'index'.
- * 	Router::connectNamed(array('page' => array('action' => 'index')), array('default' => false, 'greedy' => false));
+ * {{{ Router::connectNamed(array('page' => array('action' => 'index')), array('default' => false, 'greedy' => false)); }}}
  *
  * Parse only the page parameter if the current action is 'index' and the controller is 'pages'.
- * 	Router::connectNamed(array('page' => array('action' => 'index', 'controller' => 'pages')), array('default' => false, 'greedy' => false));
+ * {{{ Router::connectNamed(array('page' => array('action' => 'index', 'controller' => 'pages')), array('default' => false, 'greedy' => false)); }}}
  *
  * @param array $named A list of named parameters. Key value pairs are accepted where values are either regex strings to match, or arrays as seen above.
  * @param array $options Allows to control all settings: separator, greedy, reset, default
@@ -275,12 +275,15 @@ function connectNamed($named, $options = array()) {
 	}
 /**
  * Creates REST resource routes for the given controller(s)
- *
- * @param mixed $controller		A controller name or array of controller names (i.e. "Posts" or "ListItems")
- * @param array $options		Options to use when generating REST routes
- *					'id' -		The regular expression fragment to use when matching IDs.  By default, matches
- *								integer values and UUIDs.
- *					'prefix' -	URL prefix to use for the generated routes.  Defaults to '/'.
+ * 
+ * Options:
+ * 
+ * - 'id' - The regular expression fragment to use when matching IDs.  By default, matches
+ *    integer values and UUIDs.
+ * - 'prefix' - URL prefix to use for the generated routes.  Defaults to '/'.
+ * 
+ * @param mixed $controller A controller name or array of controller names (i.e. "Posts" or "ListItems")
+ * @param array $options Options to use when generating REST routes
  * @return void
  * @access public
  * @static
@@ -732,19 +735,20 @@ function promote($which = null) {
  *
  * Returns an URL pointing to a combination of controller and action. Param
  * $url can be:
- *	+ Empty - the method will find adress to actuall controller/action.
- *	+ '/' - the method will find base URL of application.
- *	+ A combination of controller/action - the method will find url for it.
+ * 
+ * - Empty - the method will find adress to actuall controller/action.
+ * - '/' - the method will find base URL of application.
+ * - A combination of controller/action - the method will find url for it.
  *
- * @param  mixed  $url    Cake-relative URL, like "/products/edit/92" or "/presidents/elect/4"
- *                        or an array specifying any of the following: 'controller', 'action',
- *                        and/or 'plugin', in addition to named arguments (keyed array elements),
- *                        and standard URL arguments (indexed array elements)
- * @param mixed $options If (bool)true, the full base URL will be prepended to the result. 
- *                       If an array accepts the following keys
- *                           escape - used when making urls embedded in html escapes query string '&'
- *                           full - if true the full base URL will be prepended.
- * @return string  Full translated URL with base path.
+ * @param mixed $url Cake-relative URL, like "/products/edit/92" or "/presidents/elect/4"
+ *   or an array specifying any of the following: 'controller', 'action',
+ *   and/or 'plugin', in addition to named arguments (keyed array elements),
+ *   and standard URL arguments (indexed array elements)
+ * @param mixed $full If (bool) true, the full base URL will be prepended to the result.
+ *   If an array accepts the following keys
+ *    - escape - used when making urls embedded in html escapes query string '&'
+ *    - full - if true the full base URL will be prepended.
+ * @return string Full translated URL with base path.
  * @access public
  * @static
  */