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,12 +303,11 @@ function remoteTimer($options = null) {
  * (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
- *                      parameters, including:
- *                          - 'params' => Acts as the form target
- *                          - 'type' => 'post' or 'get'
- *                          - 'options' => An array containing all HTML and script options used to
- *                             generate the form tag and Ajax request.
+ * @param mixed $params Either a string identifying the form target, or an array of method parameters, including:
+ *  - 'params' => Acts as the form target
+ *  - 'type' => 'post' or 'get'
+ *  - 'options' => An array containing all HTML and script options used to
+ *  generate the form tag and Ajax request.
  * @param array $type How form data is posted: 'get' or 'post'
  * @param array $options Callback/HTML options
  * @return string JavaScript/HTML code

cake/libs/view/helpers/form.php

@@ -72,16 +72,18 @@ class FormHelper extends AppHelper {
 	var $requestType = null;
 /**
  * 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 @@ function isFieldError($field) {
 /**
  * Returns a formatted error message for given FORM field, NULL if no errors.
  *
- * @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
+ * 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
  * @return string If there are errors this method returns an error message, otherwise null.
  * @access public
  */
@@ -553,17 +557,18 @@ function inputs($fields = null, $blacklist = null) {
 	}
 /**
  * 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.
- *		'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
+ * @return string Completed form widget 
  */
 	function input($fieldName, $options = array()) {
 		$view =& ClassRegistry::getObject('view');
@@ -824,10 +829,10 @@ function input($fieldName, $options = array()) {
  *
  * @param string $fieldName Name of a field, like this "Modelname.fieldname"
  * @param array $options Array of HTML attributes.
- *		'value' - the value of the checkbox
- *		'checked' - boolean indicate that this checkbox is checked.
+ * - 'value' - the value of the checkbox
+ * - 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.
+ *    checkbox is bound to a model.  This should probably be re-evaluated in future versions.
  * @return string An HTML text input element
  */
 	function checkbox($fieldName, $options = array()) {
@@ -854,14 +859,16 @@ function checkbox($fieldName, $options = array()) {
 /**
  * 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()) {
@@ -1069,11 +1076,11 @@ function button($title, $options = array()) {
 /**
  * Creates a submit button element.
  *
- * @param  string  $caption	 The label appearing on the button OR if string contains :// or the
- * 						extension .jpg, .jpe, .jpeg, .gif, .png use an image if the extension
- * 						exists, AND the first character is /, image is relative to webroot,
- *						OR if the first character is not /, image is relative to webroot/img.
- * @param  array   $options
+ * @param string $caption The label appearing on the button OR if string contains :// or the
+ *  extension .jpg, .jpe, .jpeg, .gif, .png use an image if the extension
+ *  exists, AND the first character is /, image is relative to webroot,
+ *  OR if the first character is not /, image is relative to webroot/img.
+ * @param array $options 
  * @return string A HTML submit button
  */
 	function submit($caption = null, $options = array()) {
@@ -1135,18 +1142,21 @@ function submit($caption = null, $options = array()) {
 /**
  * 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
+ *    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.
+ *   from POST data will be used when available.
+ * @param array $attributes The HTML attributes of the select element.
  * @param mixed $showEmpty If true, the empty select option is shown.  If a string,
- *						   that string is displayed as the empty element.
+ *   that string is displayed as the empty element.
  * @return string Formatted SELECT element
  */
 	function select($fieldName, $options = array(), $selected = null, $attributes = array(), $showEmpty = '') {
@@ -1300,11 +1310,13 @@ function year($fieldName, $minYear = null, $maxYear = null, $selected = null, $a
 /**
  * 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 @@ function meridian($fieldName, $selected = null, $attributes = array(), $showEmpt
 /**
  * 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/html.php

@@ -531,7 +531,7 @@ function tableCells($data, $oddTrOptions = null, $evenTrOptions = null, $useCoun
  *
  * @param string $name Tag name.
  * @param string $text String content that will appear inside the div element.
- *			If null, only a start tag will be printed
+ *   If null, only a start tag will be printed
  * @param array $attributes Additional HTML attributes of the DIV tag
  * @param boolean $escape If true, $text will be HTML-escaped
  * @return string The formatted tag element
@@ -555,7 +555,7 @@ function tag($name, $text = null, $attributes = array(), $escape = false) {
  *
  * @param string $class CSS class name of the div element.
  * @param string $text String content that will appear inside the div element.
- *			If null, only a start tag will be printed
+ *   If null, only a start tag will be printed
  * @param array $attributes Additional HTML attributes of the DIV tag
  * @param boolean $escape If true, $text will be HTML-escaped
  * @return string The formatted DIV element

cake/libs/view/helpers/javascript.php

@@ -154,14 +154,15 @@ function __construct($options = array()) {
  *
  * @param string $script The JavaScript to be wrapped in SCRIPT tags.
  * @param array $options Set of options:
- *             - allowCache: boolean, designates whether this block is cacheable using the
- *               current cache settings.
- *             - safe: boolean, whether this block should be wrapped in CDATA tags.  Defaults
- *               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).
+ * - allowCache: boolean, designates whether this block is cacheable using the
+ * current cache settings.
+ * - safe: boolean, whether this block should be wrapped in CDATA tags.  Defaults
+ * 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.
+ *   if 'inline' is set to false.
  */
 	function codeBlock($script = null, $options = array()) {
 		if (!empty($options) && !is_array($options)) {

cake/libs/view/helpers/number.php

@@ -85,7 +85,7 @@ function toPercentage($number, $precision = 2) {
  *
  * @param float $number A floating point number
  * @param integer $options if int then places, if string then before, if (,.-) then use it
- * 							or array with places and before keys
+ *   or array with places and before keys
  * @return string formatted number
  * @static
  */
@@ -128,7 +128,7 @@ function format($number, $options = false) {
  *
  * @param float $number
  * @param string $currency Shortcut to default options. Valid values are 'USD', 'EUR', 'GBP', otherwise
- *               set at least 'before' and 'after' options.
+ *   set at least 'before' and 'after' options.
  * @param array $options
  * @return string Number formatted as a currency.
  */

cake/libs/view/helpers/paginator.php

@@ -47,20 +47,21 @@ 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
- *                             parsed and constants are replaced 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()
- * - <i>$options['url']['sort']</i>  the key that the recordset is sorted.
- * - <i>$options['url']['direction']</i> Direction of the sorting (default: 'asc').
- * - <i>$options['url']['page']</i> Page # to display.
- * - <i>$options['model']</i> The name of the model.
- * - <i>$options['escape']</i> Defines if the title field for the link should be escaped (default: true).
- * - <i>$options['update']</i> DOM id of the element updated with the results of the AJAX call.
+ * 
+ *  - <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 parsed and constants are replaced 
+ *   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()
+ *  - <i>$options['url']['sort']</i>  the key that the recordset is sorted.
+ *  - <i>$options['url']['direction']</i> Direction of the sorting (default: 'asc').
+ *  - <i>$options['url']['page']</i> Page # to display.
+ *  - <i>$options['model']</i> The name of the model.
+ *  - <i>$options['escape']</i> Defines if the title field for the link should be escaped (default: true).
+ *  - <i>$options['update']</i> DOM id of the element updated with the results of the AJAX call.
  *                             If this key isn't specified Paginator will use plain HTML links.
- * - <i>$options['indicator']</i> DOM id of the element that will be shown when doing AJAX requests.
+ *  - <i>$options['indicator']</i> DOM id of the element that will be shown when doing AJAX requests.
  *
  * @var array
  */
@@ -83,8 +84,8 @@ function params($model = null) {
 /**
  * Sets default options for all pagination links
  *
- * @param  mixed $options Default options for pagination links. If a string is supplied - it
- *                        is used as the DOM id element to update. See #options for list of keys.
+ * @param  mixed $options Default options for pagination links. If a string is supplied - it 
+ * is used as the DOM id element to update. See #options for list of keys.
  */
 	function options($options = array()) {
 		if (is_string($options)) {
@@ -129,7 +130,7 @@ function current($model = null) {
  * @param  string $model Optional model name.  Uses the default if none is specified.
  * @param  mixed $options Options for pagination links. See #options for list of keys.
  * @return string The name of the key by which the recordset is being sorted, or
- *                null if the results are not currently sorted.
+ *  null if the results are not currently sorted.
  */
 	function sortKey($model = null, $options = array()) {
 		if (empty($options)) {
@@ -157,7 +158,7 @@ function sortKey($model = null, $options = array()) {
  * @param  string $model Optional model name.  Uses the default if none is specified.
  * @param  mixed $options Options for pagination links. See #options for list of keys.
  * @return string The direction by which the recordset is being sorted, or
- *                null if the results are not currently sorted.
+ *  null if the results are not currently sorted.
  */
 	function sortDir($model = null, $options = array()) {
 		$dir = null;
@@ -208,8 +209,8 @@ function next($title = 'Next >>', $options = array(), $disabledTitle = null, $di
  * @param  string $title Title for the link.
  * @param  string $key The name of the key that the recordset should be sorted.
  * @param  array $options Options for sorting link. See #options for list of keys.
- * @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified
- *                key the returned link will sort by 'desc'.
+ * @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified 
+ *  key the returned link will sort by 'desc'.
  */
 	function sort($title, $key = null, $options = array()) {
 		$options = array_merge(array('url' => array(), 'model' => null), $options);

cake/libs/view/helpers/time.php

@@ -284,12 +284,13 @@ function toRSS($dateString, $userOffset = null) {
 /**
  * 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
- *  'userOffset' => Users offset from GMT (in hours)
+ * 
+ * - 'format' => a fall back format if the relative time is longer than the duration specified by end
+ * - '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
@@ -464,7 +465,7 @@ function timeAgoInWords($dateTime, $options = array()) {
  *
  * @param mixed $dateTime Datetime string (strtotime-compatible) or Unix timestamp
  * @param mixed $options Default format string, if timestamp is used in $dateTime, or an array of options to be passed
- *						 on to timeAgoInWords().
+ *   on to timeAgoInWords().
  * @return string Relative time string.
  * @see		TimeHelper::timeAgoInWords
  */