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/class_registry.php

@@ -72,20 +72,26 @@ class ClassRegistry {
 /**
  * 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,
+ * Examples
- * 	stored in the registry and returned.
+ * Simple Use: Get a Post model instance ```ClassRegistry::init('Post');```
- *   Required: array('class' => 'ClassName', 'alias' => 'AliasNameStoredInTheRegistry', 'type' => 'TypeOfClass');
+ * 
- *   Model Classes can accept optional array('id' => $id, 'table' => $table, 'ds' => $ds, 'alias' => $alias);
+ * 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')
  * );
- *
+ * }}}
+ * @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,17 +246,20 @@ class Configure extends Object {
 /**
  * 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
  * @param array $config Name of var to write

cake/libs/controller/controller.php

@@ -321,7 +321,6 @@ class Controller extends Object {
 		foreach ($parentMethods as $key => $value) {
 			$parentMethods[$key] = strtolower($value);
 		}
-
 		$this->methods = array_diff($childMethods, $parentMethods);
 		parent::__construct();
 	}

cake/libs/model/behaviors/containable.php

@@ -47,16 +47,16 @@ 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
- *
  * - autoFields: (boolean, optional) auto-add needed fields to fetch requested
  *   bindings. DEFAULTS TO: true
  *

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

@@ -514,7 +514,7 @@ class DboDb2 extends DboSource {
  * key 0.
  *
  * 1. Gets the column headers
- *
+ * {{{
  * Post.id
  * Post.title
  *
@@ -529,7 +529,7 @@ class DboDb2 extends DboSource {
  *          [0] => Post
  *          [1] => title
  *      )
- *
+ * }}}
  * @param unknown_type $results
  */
 	function resultSet(&$results, $sql = null) {

cake/libs/model/schema.php

@@ -167,10 +167,12 @@ class CakeSchema extends Object {
 /**
  * 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 @@ class Router extends Object {
  *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
@@ -276,11 +276,14 @@ class Router extends Object {
 /**
  * Creates REST resource routes for the given controller(s)
  * 
+ * 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
- *					'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 '/'.
  * @return void
  * @access public
  * @static
@@ -732,18 +735,19 @@ class Router extends Object {
  *
  * 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.
+ * - Empty - the method will find adress to actuall controller/action.
- *	+ A combination of controller/action - the method will find url for it.
+ * - '/' - 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. 
+ * @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 '&'
+ *    - escape - used when making urls embedded in html escapes query string '&'
- *                           full - if true the full base URL will be prepended.
+ *    - full - if true the full base URL will be prepended.
  * @return string Full translated URL with base path.
  * @access public
  * @static