Updating doc blocks in helpers. Helps generate cleaner API.

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

cake/libs/view/helpers/ajax.php

@@ -303,8 +303,7 @@ class AjaxHelper extends AppHelper {
  * (all elements available in params).  The options for defining callbacks is the same
  * as AjaxHelper::link().
  *
- * @param mixed $params Either a string identifying the form target, or an array of method
+ * @param mixed $params Either a string identifying the form target, or an array of method parameters, including:
- *                      parameters, including:
  *  - 'params' => Acts as the form target
  *  - 'type' => 'post' or 'get'
  *  - 'options' => An array containing all HTML and script options used to

cake/libs/view/helpers/form.php

@@ -73,15 +73,17 @@ class FormHelper extends AppHelper {
 /**
  * Returns an HTML FORM element.
  * 
+ * Options:
+ * 
+ * - 'type' Form method defaults to POST
+ * - 'action'  The Action the form submits to. Can be a string or array,
+ * - 'url'  The url the form submits to. Can be a string or a url array,
+ * - 'default'  Allows for the creation of Ajax forms.
+ * - 'onsubmit' Used in conjunction with 'default' to create ajax forms. 
+ * 
  * @access public
  * @param string $model The model object which the form is being defined for
  * @param array	 $options
- *			'type' Form method defaults to POST
- * 			'action'  The Action the form submits to. Can be a string or array,
- *			'url'  The url the form submits to. Can be a string or a url array,
- *			'default'  Allows for the creation of Ajax forms.
- *			'onsubmit' Used in conjunction with 'default' to create ajax forms.
- *
  * @return string An formatted opening FORM tag.
  */
 	function create($model = null, $options = array()) {
@@ -375,13 +377,15 @@ class FormHelper extends AppHelper {
 /**
  * Returns a formatted error message for given FORM field, NULL if no errors.
  *
+ * Options:
+ * 
+ * - 'escape'  bool  Whether or not to html escape the contents of the error.
+ * - 'wrap'  mixed  Whether or not the error message should be wrapped in a div. If a
+ *   string, will be used as the HTML tag to use.
+ * - 'class'  string  The classname for the error message
  * @param string $field  A field name, like "Modelname.fieldname"
  * @param mixed $text  Error message or array of $options
  * @param array $options  Rendering options for <div /> wrapper tag
- *			'escape'  bool  Whether or not to html escape the contents of the error.
- *			'wrap'  mixed  Whether or not the error message should be wrapped in a div. If a
- * 					string, will be used as the HTML tag to use.
- *			'class'  string  The classname for the error message
  * @return string If there are errors this method returns an error message, otherwise null.
  * @access public
  */
@@ -554,16 +558,17 @@ class FormHelper extends AppHelper {
 /**
  * Generates a form input element complete with label and wrapper div
  * 
+ * Options - See each field type method for more information.
+ * 
+ * - 'type' - Force the type of widget you want. e.g. ```type => 'select'```
+ * - 'label' - control the label
+ * - 'div' - control the wrapping div element
+ * - 'options' - for widgets that take options e.g. radio, select
+ * - 'error' - control the error message that is produced
+ * 
  * @param string $fieldName This should be "Modelname.fieldname"
  * @param array $options - Each type of input takes different options.
- * 		See each field type method for more information.
+ * @return string Completed form widget 
- *		'type' - Force the type of widget you want. e.g. type => 'select'
- *		'label' - control the label
- *		'div' - control the wrapping div element
- *		'options' - for widgets that take options e.g. radio, select
- * 		'error' - control the error message that is produced
- *
- * @return string
  */
 	function input($fieldName, $options = array()) {
 		$view =& ClassRegistry::getObject('view');
@@ -824,8 +829,8 @@ class FormHelper extends AppHelper {
  *
  * @param string $fieldName Name of a field, like this "Modelname.fieldname"
  * @param array $options Array of HTML attributes.
- *		'value' - the value of the checkbox
+ * - 'value' - the value of the checkbox
- *		'checked' - boolean indicate that this checkbox is checked.
+ * - checked' - boolean indicate that this checkbox is checked.
  * @todo Right now, automatically setting the 'checked' value is dependent on whether or not the
  *    checkbox is bound to a model.  This should probably be re-evaluated in future versions.
  * @return string An HTML text input element
@@ -854,14 +859,16 @@ class FormHelper extends AppHelper {
 /**
  * Creates a set of radio widgets.
  *
+ * Attributes:
+ * 
+ * - 'separator' - define the string in between the radio buttons
+ * - 'legend' - control whether or not the widget set has a fieldset & legend
+ * - 'value' - indicate a value that is should be checked
+ * - 'label' - boolean to indicate whether or not labels for widgets show be displayed
+ * 
  * @param  string  	$fieldName 		Name of a field, like this "Modelname.fieldname"
  * @param  array	$options		Radio button options array.
  * @param  array	$attributes		Array of HTML attributes.
- *		'separator' - define the string in between the radio buttons
- *		'legend' - control whether or not the widget set has a fieldset & legend
- *		'value' - indicate a value that is should be checked
- * 		'label' - boolean to indicate whether or not labels for widgets show be displayed
- *
  * @return string
  */
 	function radio($fieldName, $options = array(), $attributes = array()) {
@@ -1135,16 +1142,19 @@ class FormHelper extends AppHelper {
 /**
  * Returns a formatted SELECT element.
  *
+ * Attributes:
+ * 
+ * - 'showParents' - If included in the array and set to true, an additional option element
+ *   will be added for the parent of each option group.
+ * - 'multiple' - show a multiple select box.  If set to 'checkbox' multiple checkboxes will be
+ *   created instead.
+ * 
  * @param string $fieldName Name attribute of the SELECT
  * @param array $options Array of the OPTION elements (as 'value'=>'Text' pairs) to be used in the
  *    SELECT element
  * @param mixed $selected The option selected by default.  If null, the default value
  *   from POST data will be used when available.
  * @param array $attributes The HTML attributes of the select element.
- *		'showParents' - If included in the array and set to true, an additional option element
- *						will be added for the parent of each option group.
- *		'multiple' - show a multiple select box.  If set to 'checkbox' multiple checkboxes will be
- * 					 created instead.
  * @param mixed $showEmpty If true, the empty select option is shown.  If a string,
  *   that string is displayed as the empty element.
  * @return string Formatted SELECT element
@@ -1300,11 +1310,13 @@ class FormHelper extends AppHelper {
 /**
  * Returns a SELECT element for months.
  *
+ * Attributes:
+ * 
+ * - 'monthNames' is set and false 2 digit numbers will be used instead of text.
+ *
  * @param string $fieldName Prefix name for the SELECT element
  * @param string $selected Option which is selected.
  * @param array $attributes Attributes for the select element
- *		'monthNames' is set and false 2 digit numbers will be used instead of text.
- *
  * @param boolean $showEmpty Show/hide the empty select option
  * @return string
  */
@@ -1460,16 +1472,18 @@ class FormHelper extends AppHelper {
 /**
  * Returns a set of SELECT elements for a full datetime setup: day, month and year, and then time.
  *
+ * Attributes:
+ * 
+ * - 'monthNames' If set and false numbers will be used for month select instead of text.
+ * - 'minYear' The lowest year to use in the year select
+ * - 'maxYear' The maximum year to use in the year select
+ * - 'interval' The interval for the minutes select. Defaults to 1
+ * - 'separator' The contents of the string between select elements. Defaults to '-'
  * @param string $fieldName Prefix name for the SELECT element
  * @param string $dateFormat DMY, MDY, YMD or NONE.
  * @param string $timeFormat 12, 24, NONE
  * @param string $selected Option which is selected.
  * @param string $attributes array of Attributes
- *		'monthNames' If set and false numbers will be used for month select instead of text.
- *		'minYear' The lowest year to use in the year select
- *		'maxYear' The maximum year to use in the year select
- *		'interval' The interval for the minutes select. Defaults to 1
- *		'separator' The contents of the string between select elements. Defaults to '-'
  * @param bool $showEmpty Whether or not to show an empty default value.
  * @return string The HTML formatted OPTION element
  */

cake/libs/view/helpers/javascript.php

@@ -160,6 +160,7 @@ class JavascriptHelper extends AppHelper {
  * to helper's object configuration.
  * - inline: whether the block should be printed inline, or written
  * to cached for later output (i.e. $scripts_for_layout).
+ * 
  * @return string The full SCRIPT element, with the JavaScript inside it, or null,
  *   if 'inline' is set to false.
  */

cake/libs/view/helpers/paginator.php

@@ -47,9 +47,10 @@ class PaginatorHelper extends AppHelper {
  * Holds the default options for pagination links
  *
  * The values that may be specified are:
+ * 
  *  - <i>$options['format']</i> Format of the counter. Supported formats are 'range' and 'pages'
- *                             and custom (default). In the default mode the supplied string is
+ *   and custom (default). In the default mode the supplied string is parsed and constants are replaced 
- *                             parsed and constants are replaced by their actual values.
+ *   by their actual values.
  *   Constants: %page%, %pages%, %current%, %count%, %start%, %end% .
  *  - <i>$options['separator']</i> The separator of the actual page and number of pages (default: ' of ').
  *  - <i>$options['url']</i> Url of the action. See Router::url()

cake/libs/view/helpers/time.php

@@ -284,12 +284,13 @@ class TimeHelper extends AppHelper {
 /**
  * Returns either a relative date or a formatted date depending
  * on the difference between the current time and given datetime.
- * $datetime should be in a <i>strtotime</i>-parsable format, like MySQL's datetime datatype.
+ * $datetime should be in a <i>strtotime</i> - parsable format, like MySQL's datetime datatype.
  *
  * Options:
- *  'format' => a fall back format if the relative time is longer than the duration specified by end
+ * 
- *  'end' =>  The end of relative time telling
+ * - 'format' => a fall back format if the relative time is longer than the duration specified by end
- *  'userOffset' => Users offset from GMT (in hours)
+ * - 'end' => The end of relative time telling
+ * - 'userOffset' => Users offset from GMT (in hours)
  *
  * Relative dates look something like this:
  *	3 weeks, 4 days ago