Updates for ApiGen and other general edits

Author: bcrowe

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,13 +66,16 @@ public function __construct(View $View, $settings = array()) {
 
 /**
  * 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) {
 		return call_user_func_array(array($this->_engine, $method), $params);
 	}
 
 /**
+ * Formats a number with a level of precision.
+ *
  * @see: Cake\Utility\Number::precision()
  *
  * @param float $number A floating point number.
@@ -85,6 +88,8 @@ public function precision($number, $precision = 3) {
 	}
 
 /**
+ * Returns a formatted-for-humans file size.
+ *
  * @see: Cake\Utility\Number::toReadableSize()
  *
  * @param integer $size Size in bytes
@@ -96,6 +101,12 @@ public function toReadableSize($size) {
 	}
 
 /**
+ * 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 @@ public function toPercentage($number, $precision = 2, $options = array()) {
 	}
 
 /**
+ * Formats a number into a currency format.
+ *
  * @see: Cake\Utility\Number::format()
  *
  * @param float $number A floating point number
@@ -122,12 +135,41 @@ public function format($number, $options = false) {
 	}
 
 /**
+ * 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 @@ public function currency($number, $currency = null, $options = array()) {
 	}
 
 /**
+ * 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 @@ public function addFormat($formatName, $options) {
 	}
 
 /**
- * @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 @@ public function autoLink($text, $options = array()) {
 	}
 
 /**
+ * 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 @@ public function autoParagraph($text) {
 	}
 
 /**
+ * Strips given text of all links (<a href=....)
+ *
  * @see String::stripLinks()
  *
  * @param string $text Text
@@ -263,6 +268,16 @@ public function stripLinks($text) {
 	}
 
 /**
+ * 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 @@ public function truncate($text, $length = 100, $options = array()) {
 	}
 
 /**
+ * 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 @@ public function excerpt($text, $phrase, $radius = 100, $ending = '...') {
 	}
 
 /**
+ * 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