Updates for ApiGen and other general edits

src/Utility/Number.php

@@ -80,7 +80,7 @@ class Number {
 	);
 
 /**
- * Default currency used by CakeNumber::currency()
+ * Default currency used by Number::currency()
  *
  * @var string
  */

src/View/Helper/NumberHelper.php

@@ -66,6 +66,7 @@ class NumberHelper extends Helper {
 
 /**
  * Call methods from Cake\Utility\Number utility class
+ *
  * @return mixed Whatever is returned by called method, or false on failure
  */
 	public function __call($method, $params) {
@@ -73,6 +74,8 @@ class NumberHelper extends Helper {
 	}
 
 /**
+ * Formats a number with a level of precision.
+ *
  * @see: Cake\Utility\Number::precision()
  *
  * @param float $number A floating point number.
@@ -85,6 +88,8 @@ class NumberHelper extends Helper {
 	}
 
 /**
+ * Returns a formatted-for-humans file size.
+ *
  * @see: Cake\Utility\Number::toReadableSize()
  *
  * @param integer $size Size in bytes
@@ -96,6 +101,12 @@ class NumberHelper extends Helper {
 	}
 
 /**
+ * Formats a number into a percentage string.
+ *
+ * Options:
+ *
+ * - `multiply`: Multiply the input value by 100 for decimal percentages.
+ *
  * @see: Cake\Utility\Number::toPercentage()
  *
  * @param float $number A floating point number
@@ -109,6 +120,8 @@ class NumberHelper extends Helper {
 	}
 
 /**
+ * Formats a number into a currency format.
+ *
  * @see: Cake\Utility\Number::format()
  *
  * @param float $number A floating point number
@@ -122,12 +135,41 @@ class NumberHelper extends Helper {
 	}
 
 /**
+ * Formats a number into a currency format.
+ *
+ * ### Options
+ *
+ * - `wholeSymbol` - The currency symbol to use for whole numbers,
+ *   greater than 1, or less than -1.
+ * - `wholePosition` - The position the whole symbol should be placed
+ *   valid options are 'before' & 'after'.
+ * - `fractionSymbol` - The currency symbol to use for fractional numbers.
+ * - `fractionPosition` - The position the fraction symbol should be placed
+ *   valid options are 'before' & 'after'.
+ * - `before` - The currency symbol to place before whole numbers
+ *   ie. '$'. `before` is an alias for `wholeSymbol`.
+ * - `after` - The currency symbol to place after decimal numbers
+ *   ie. 'c'. Set to boolean false to use no decimal symbol.
+ *   eg. 0.35 => $0.35. `after` is an alias for `fractionSymbol`
+ * - `zero` - The text to use for zero values, can be a
+ *   string or a number. ie. 0, 'Free!'
+ * - `places` - Number of decimal places to use. ie. 2
+ * - `fractionExponent` - Fraction exponent of this specific currency. Defaults to 2.
+ * - `thousands` - Thousands separator ie. ','
+ * - `decimals` - Decimal separator symbol ie. '.'
+ * - `negative` - Symbol for negative numbers. If equal to '()',
+ *   the number will be wrapped with ( and )
+ * - `escape` - Should the output be escaped for html special characters.
+ *   The default value for this option is controlled by the currency settings.
+ *   By default all currencies contain utf-8 symbols and don't need this changed. If you require
+ *   non HTML encoded symbols you will need to update the settings with the correct bytes.
+ *
  * @see: Cake\Utility\Number::currency()
  *
  * @param float $number
  * @param string $currency Shortcut to default options. Valid values are 'USD', 'EUR', 'GBP', otherwise
  *   set at least 'before' and 'after' options.
- * 'USD' is the default currency, use CakeNumber::defaultCurrency() to change this default.
+ * 'USD' is the default currency, use Number::defaultCurrency() to change this default.
  * @param array $options
  * @return string Number formatted as a currency.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/number.html#NumberHelper::currency
@@ -137,6 +179,18 @@ class NumberHelper extends Helper {
 	}
 
 /**
+ * Add a currency format to the Number helper. Makes reusing
+ * currency formats easier.
+ *
+ * {{{ $number->addFormat('NOK', array('before' => 'Kr. ')); }}}
+ *
+ * You can now use `NOK` as a shortform when formatting currency amounts.
+ *
+ * {{{ $number->currency($value, 'NOK'); }}}
+ *
+ * Added formats are merged with the defaults defined in Cake\Utility\Number::$_currencyDefaults
+ * See Cake\Utility\Number::currency() for more information on the various options and their function.
+ *
  * @see: Cake\Utility\Number::addFormat()
  *
  * @param string $formatName The format name to be used in the future.
@@ -150,7 +204,8 @@ class NumberHelper extends Helper {
 	}
 
 /**
- * @see CakeNumber::defaultCurrency()
+ * Getter/setter for default currency
+ * @see  Cake\Utility\Number::defaultCurrency()
  *
  * @param string $currency The currency to be used in the future.
  * @return void

src/View/Helper/TextHelper.php

@@ -216,6 +216,9 @@ class TextHelper extends Helper {
 	}
 
 /**
+ * Highlights a given phrase in a text. You can specify any expression in highlighter that
+ * may include the \1 expression to include the $phrase found.
+ *
  * @see String::highlight()
  *
  * @param string $text Text to search the phrase in
@@ -252,6 +255,8 @@ class TextHelper extends Helper {
 	}
 
 /**
+ * Strips given text of all links (<a href=....)
+ *
  * @see String::stripLinks()
  *
  * @param string $text Text
@@ -263,6 +268,16 @@ class TextHelper extends Helper {
 	}
 
 /**
+ * Truncates text starting from the end.
+ *
+ * Cuts a string to the length of $length and replaces the first characters
+ * with the ellipsis if the text is longer than length.
+ *
+ * ### Options:
+ *
+ * - `ellipsis` Will be used as Beginning and prepended to the trimmed string
+ * - `exact` If false, $text will not be cut mid-word
+ *
  * @see String::truncate()
  *
  * @param string $text String to truncate.
@@ -276,6 +291,9 @@ class TextHelper extends Helper {
 	}
 
 /**
+ * Extracts an excerpt from the text surrounding the phrase with a number of characters on each side
+ * determined by radius.
+ *
  * @see String::excerpt()
  *
  * @param string $text String to search the phrase in
@@ -290,6 +308,8 @@ class TextHelper extends Helper {
 	}
 
 /**
+ * Creates a comma separated list where the last two items are joined with 'and', forming natural English
+ *
  * @see String::toList()
  *
  * @param array $list The list to be joined

src/View/Helper/TimeHelper.php

@@ -65,6 +65,7 @@ class TimeHelper extends Helper {
 
 /**
  * Call methods from Cake\Utility\Time utility class
+ *
  * @return mixed Whatever is returned by called method, or false on failure
  */
 	public function __call($method, $params) {
@@ -72,6 +73,9 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Converts a string representing the format for the function strftime and returns a
+ * windows safe and i18n aware format.
+ *
  * @see Cake\Utility\Time::convertSpecifiers()
  *
  * @param string $format Format with specifiers for strftime function.
@@ -85,6 +89,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Converts given time (in server's time zone) to user's local time, given his/her timezone.
+ *
  * @see Cake\Utility\Time::convert()
  *
  * @param string $serverTime UNIX timestamp
@@ -97,16 +103,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
- * @see Cake\Utility\Time::serverOffset()
+ * Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
  *
- * @return integer Offset
- * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
- */
-	public function serverOffset() {
-		return $this->_engine->serverOffset();
-	}
-
-/**
  * @see Cake\Utility\Time::fromString()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -119,6 +117,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns a nicely formatted date string for given Datetime string.
+ *
  * @see Cake\Utility\Time::nice()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -132,18 +132,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
- * @see Cake\Utility\Time::niceShort()
+ * Returns a partial SQL string to search for all records between two dates.
  *
- * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime objectp
- * @param string|DateTimeZone $timezone User's timezone string or DateTimeZone object
- * @return string Described, relative date string
- * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/time.html#formatting
- */
-	public function niceShort($dateString = null, $timezone = null) {
-		return $this->_engine->niceShort($dateString, $timezone);
-	}
-
-/**
  * @see Cake\Utility\Time::daysAsSql()
  *
  * @param integer|string|DateTime $begin UNIX timestamp, strtotime() valid string or DateTime object
@@ -158,6 +148,9 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns a partial SQL string to search for all records between two times
+ * occurring on the same day.
+  *
  * @see Cake\Utility\Time::dayAsSql()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -171,6 +164,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if given datetime string is today.
+ *
  * @see Cake\Utility\Time::isToday()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -183,6 +178,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if given datetime string is within this week.
+ *
  * @see Cake\Utility\Time::isThisWeek()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -195,6 +192,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if given datetime string is within this month
+ *
  * @see Cake\Utility\Time::isThisMonth()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -207,6 +206,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if given datetime string is within current year.
+ *
  * @see Cake\Utility\Time::isThisYear()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -219,6 +220,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if given datetime string was yesterday.
+ *
  * @see Cake\Utility\Time::wasYesterday()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -232,6 +235,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if given datetime string is tomorrow.
+ *
  * @see Cake\Utility\Time::isTomorrow()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -244,6 +249,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns the quarter
+ *
  * @see Cake\Utility\Time::toQuarter()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -256,6 +263,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
+ *
  * @see Cake\Utility\Time::toUnix()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -268,6 +277,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns a date formatted for Atom RSS feeds.
+ *
  * @see Cake\Utility\Time::toAtom()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -292,9 +303,11 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * * Formats date for RSS feeds
+ *
  * @see Cake\Utility\Time::timeAgoInWords()
  *
- * ## Addition options
+ * ## Additional options
  *
  * - `element` - The element to wrap the formatted time in.
  *   Has a few additional options:
@@ -339,6 +352,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if specified datetime was within the interval specified, else false.
+ *
  * @see Cake\Utility\Time::wasWithinLast()
  *
  * @param string|integer $timeInterval the numeric value with space then time type.
@@ -353,6 +368,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns true if specified datetime is within the interval specified, else false.
+ *
  * @see Cake\Utility\Time::isWithinLast()
  *
  * @param string|integer $timeInterval the numeric value with space then time type.
@@ -367,6 +384,8 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns gmt as a UNIX timestamp.
+ *
  * @see Cake\Utility\Time::gmt()
  *
  * @param integer|string|DateTime $string UNIX timestamp, strtotime() valid string or DateTime object
@@ -378,6 +397,21 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
+ * This function also accepts a time string and a format string as first and second parameters.
+ * In that case this function behaves as a wrapper for TimeHelper::i18nFormat()
+ *
+ * ## Examples
+ *
+ * Create localized & formatted time:
+ *
+ * {{{
+ *   Cake\Utility\Time::format('2012-02-15', '%m-%d-%Y'); // returns 02-15-2012
+ *   Cake\Utility\Time::format('2012-02-15 23:01:01', '%c'); // returns preferred date and time based on configured locale
+ *   Cake\Utility\Time::format('0000-00-00', '%d-%m-%Y', 'N/A'); // return N/A becuase an invalid date was passed
+ *   Cake\Utility\Time::format('2012-02-15 23:01:01', '%c', 'N/A', 'America/New_York'); // converts passed date to timezone
+ * }}}
+ *
  * @see Cake\Utility\Time::format()
  *
  * @param integer|string|DateTime $format date format string (or a UNIX timestamp, strtotime() valid string or DateTime object)
@@ -392,6 +426,9 @@ class TimeHelper extends Helper {
 	}
 
 /**
+ * Returns a formatted date string, given either a UNIX timestamp or a valid strtotime() date string.
+ * It takes into account the default date format for the current language if a LC_TIME file is used.
+ *
  * @see Cake\Utility\Time::i18nFormat()
  *
  * @param integer|string|DateTime $date UNIX timestamp, strtotime() valid string or DateTime object

src/View/Input/MultiCheckbox.php

@@ -134,6 +134,7 @@ class MultiCheckbox implements InputInterface {
 /**
  * Render a single checkbox & wrapper.
  *
+ * @param array $checkbox An array containing checkbox key/value option pairs
  * @return string
  */
 	protected function _renderInput($checkbox) {

src/View/Input/Radio.php

@@ -34,6 +34,8 @@ class Radio implements InputInterface {
 	protected $_templates;
 
 /**
+ * Label instance.
+ * 
  * @var Cake\View\Input\Label
  */
 	protected $_label;
@@ -126,7 +128,7 @@ class Radio implements InputInterface {
  * @param string|int $val The value of the radio input.
  * @param string|array $text The label text, or complex radio type.
  * @param array $data Additional options for input generation.
- * @return string.
+ * @return string
  */
 	protected function _renderInput($val, $text, $data) {
 		$escape = $data['escape'];

src/View/Input/SelectBox.php

@@ -179,7 +179,12 @@ class SelectBox implements InputInterface {
 /**
  * Render the contents of an optgroup element.
  *
+ * @param string $label The optgroup label text
  * @param array $optgroup The opt group data.
+ * @param array|null $disabled The options to disable.
+ * @param array|string|null $selected The options to select.
+ * @param boolean $escape Toggle HTML escaping
+ * @return string Formatted template string
  */
 	protected function _renderOptgroup($label, $optgroup, $disabled, $selected, $escape) {
 		$opts = $optgroup;

src/View/View.php

@@ -773,7 +773,7 @@ class View extends Object {
  *
  * @param string $name Name of the attribute to set.
  * @param mixed $value Value of the attribute to set.
- * @return mixed
+ * @return void
  */
 	public function __set($name, $value) {
 		$this->{$name} = $value;