Fix ApiGen errors

lib/Cake/Console/Command/ServerShell.php

@@ -26,11 +26,15 @@ class ServerShell extends AppShell {
 
 /**
  * Default ServerHost
+ *
+ * @var string
  */
 	const DEFAULT_HOST = 'localhost';
 
 /**
  * Default ListenPort
+ *
+ * @var integer
  */
 	const DEFAULT_PORT = 80;
 

lib/Cake/Console/Command/Task/ExtractTask.php

@@ -501,6 +501,7 @@ class ExtractTask extends AppShell {
  * @param array $rules the set of validation rules for the field
  * @param string $file the file name where this validation rule was found
  * @param string $domain default domain to bind the validations to
+ * @param string $category the translation category
  * @return void
  */
 	protected function _processValidationRules($field, $rules, $file, $domain, $category = 'LC_MESSAGES') {

lib/Cake/Console/ConsoleOutput.php

@@ -46,21 +46,29 @@ class ConsoleOutput {
 
 /**
  * Raw output constant - no modification of output text.
+ *
+ * @var integer
  */
 	const RAW = 0;
 
 /**
  * Plain output - tags will be stripped.
+ *
+ * @var integer
  */
 	const PLAIN = 1;
 
 /**
  * Color output - Convert known tags in to ANSI color escape codes.
+ *
+ * @var integer
  */
 	const COLOR = 2;
 
 /**
  * Constant for a newline.
+ *
+ * @var string
  */
 	const LF = PHP_EOL;
 

lib/Cake/Console/Shell.php

@@ -33,16 +33,22 @@ class Shell extends Object {
 
 /**
  * Output constant making verbose shells.
+ *
+ * @var integer
  */
 	const VERBOSE = 2;
 
 /**
  * Output constant for making normal shells.
+ *
+ * @var integer
  */
 	const NORMAL = 1;
 
 /**
  * Output constants for making quiet shells.
+ *
+ * @var integer
  */
 	const QUIET = 0;
 

lib/Cake/Controller/Component/Acl/PhpAcl.php

@@ -26,11 +26,15 @@ class PhpAcl extends Object implements AclInterface {
 
 /**
  * Constant for deny
+ *
+ * @var boolean
  */
 	const DENY = false;
 
 /**
  * Constant for allow
+ *
+ * @var boolean
  */
 	const ALLOW = true;
 
@@ -364,6 +368,8 @@ class PhpAro {
 /**
  * role to resolve to when a provided ARO is not listed in
  * the internal tree
+ *
+ * @var string
  */
 	const DEFAULT_ROLE = 'Role/default';
 

lib/Cake/Controller/Component/AuthComponent.php

@@ -39,6 +39,8 @@ class AuthComponent extends Component {
 
 /**
  * Constant for 'all'
+ *
+ * @var string
  */
 	const ALL = 'all';
 

lib/Cake/Core/App.php

@@ -66,28 +66,28 @@ class App {
 /**
  * Append paths
  *
- * @constant APPEND
+ * @var string
  */
 	const APPEND = 'append';
 
 /**
  * Prepend paths
  *
- * @constant PREPEND
+ * @var string
  */
 	const PREPEND = 'prepend';
 
 /**
  * Register package
  *
- * @constant REGISTER
+ * @var string
  */
 	const REGISTER = 'register';
 
 /**
  * Reset paths instead of merging
  *
- * @constant RESET
+ * @var boolean
  */
 	const RESET = true;
 

lib/Cake/Core/Object.php

@@ -152,6 +152,8 @@ class Object {
  *
  * @param string $msg Log message
  * @param integer $type Error type constant. Defined in app/Config/core.php.
+ * @param null|string|array $scope The scope(s) a log message is being created in.
+ *    See CakeLog::config() for more information on logging scopes.
  * @return boolean Success of log write
  */
 	public function log($msg, $type = LOG_ERR, $scope = null) {

lib/Cake/Error/ErrorHandler.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Error handler
+ * ErrorHandler class
  *
  * Provides Error Capturing for Framework errors.
  *

lib/Cake/Model/Datasource/Database/Sqlserver.php

@@ -103,6 +103,8 @@ class Sqlserver extends DboSource {
 /**
  * Magic column name used to provide pagination support for SQLServer 2008
  * which lacks proper limit/offset support.
+ *
+ * @var string
  */
 	const ROW_COUNTER = '_cake_page_rownum_';
 

lib/Cake/Network/Email/CakeEmail.php

@@ -36,35 +36,35 @@ class CakeEmail {
 /**
  * Default X-Mailer
  *
- * @constant EMAIL_CLIENT
+ * @var string
  */
 	const EMAIL_CLIENT = 'CakePHP Email';
 
 /**
  * Line length - no should more - RFC 2822 - 2.1.1
  *
- * @constant LINE_LENGTH_SHOULD
+ * @var integer
  */
 	const LINE_LENGTH_SHOULD = 78;
 
 /**
  * Line length - no must more - RFC 2822 - 2.1.1
  *
- * @constant LINE_LENGTH_MUST
+ * @var integer
  */
 	const LINE_LENGTH_MUST = 998;
 
 /**
  * Type of message - HTML
  *
- * @constant MESSAGE_HTML
+ * @var string
  */
 	const MESSAGE_HTML = 'html';
 
 /**
  * Type of message - TEXT
  *
- * @constant MESSAGE_TEXT
+ * @var string
  */
 	const MESSAGE_TEXT = 'text';
 
@@ -1308,6 +1308,7 @@ class CakeEmail {
  * Wrap the message to follow the RFC 2822 - 2.1.1
  *
  * @param string $message Message to wrap
+ * @param integer $wrapLength The line length
  * @return array Wrapped message
  */
 	protected function _wrap($message, $wrapLength = CakeEmail::LINE_LENGTH_MUST) {

lib/Cake/Routing/Router.php

@@ -85,14 +85,45 @@ class Router {
 	protected static $_validExtensions = array();
 
 /**
- * 'Constant' regular expression definitions for named route elements
+ * Regular expression for action names
  *
+ * @var string
  */
 	const ACTION = 'index|show|add|create|edit|update|remove|del|delete|view|item';
+
+/**
+ * Regular expression for years
+ *
+ * @var string
+ */
 	const YEAR = '[12][0-9]{3}';
+
+/**
+ * Regular expression for months
+ *
+ * @var string
+ */
 	const MONTH = '0[1-9]|1[012]';
+
+/**
+ * Regular expression for days
+ *
+ * @var string
+ */
 	const DAY = '0[1-9]|[12][0-9]|3[01]';
+
+/**
+ * Regular expression for auto increment IDs
+ *
+ * @var string
+ */
 	const ID = '[0-9]+';
+
+/**
+ * Regular expression for UUIDs
+ *
+ * @var string
+ */
 	const UUID = '[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}';
 
 /**

lib/Cake/Utility/Folder.php

@@ -26,7 +26,7 @@ class Folder {
  * Default scheme for Folder::copy
  * Recursively merges subfolders with the same name
  *
- * @constant MERGE
+ * @var string
  */
 	const MERGE = 'merge';
 
@@ -34,7 +34,7 @@ class Folder {
  * Overwrite scheme for Folder::copy
  * subfolders with the same name will be replaced
  *
- * @constant OVERWRITE
+ * @var string
  */
 	const OVERWRITE = 'overwrite';
 
@@ -42,7 +42,7 @@ class Folder {
  * Skip scheme for Folder::copy
  * if a subfolder with the same name exists it will be skipped
  *
- * @constant SKIP
+ * @var string
  */
 	const SKIP = 'skip';
 

lib/Cake/View/Helper/NumberHelper.php

@@ -73,6 +73,8 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * Formats a number with a level of precision.
+ *
  * @see CakeNumber::precision()
  *
  * @param float $number A floating point number.
@@ -85,6 +87,8 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * Returns a formatted-for-humans file size.
+ *
  * @see CakeNumber::toReadableSize()
  *
  * @param integer $size Size in bytes
@@ -96,6 +100,8 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * - `multiply`: Multiply the input value by 100 for decimal percentages.
+ *
  * @see CakeNumber::toPercentage()
  *
  * @param float $number A floating point number
@@ -109,6 +115,8 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * Formats a number into a currency format.
+ *
  * @see CakeNumber::format()
  *
  * @param float $number A floating point number
@@ -122,6 +130,8 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * Formats a number into a currency format.
+ *
  * @see CakeNumber::currency()
  *
  * @param float $number
@@ -137,6 +147,18 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * Add a currency format to the Number helper. Makes reusing
+ * currency formats easier.
+ *
+ * {{{ $this->Number->addFormat('NOK', array('before' => 'Kr. ')); }}}
+ *
+ * You can now use `NOK` as a shortform when formatting currency amounts.
+ *
+ * {{{ $this->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 CakeNumber::addFormat()
  *
  * @param string $formatName The format name to be used in the future.
@@ -150,6 +172,8 @@ class NumberHelper extends AppHelper {
 	}
 
 /**
+ * Getter/setter for default currency
+ *
  * @see CakeNumber::defaultCurrency()
  *
  * @param string $currency The currency to be used in the future.

lib/Cake/View/Helper/TextHelper.php

@@ -215,6 +215,9 @@ class TextHelper extends AppHelper {
 	}
 
 /**
+ * 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
@@ -251,6 +254,8 @@ class TextHelper extends AppHelper {
 	}
 
 /**
+ * Strips given text of all links (<a href=....)
+ *
  * @see String::stripLinks()
  *
  * @param string $text Text
@@ -262,6 +267,16 @@ class TextHelper extends AppHelper {
 	}
 
 /**
+ * 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.
@@ -275,6 +290,9 @@ class TextHelper extends AppHelper {
 	}
 
 /**
+ * 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
@@ -289,6 +307,8 @@ class TextHelper extends AppHelper {
 	}
 
 /**
+ * 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

lib/Cake/View/Helper/TimeHelper.php

@@ -122,6 +122,9 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Converts a string representing the format for the function strftime and returns a
+ * windows safe and i18n aware format.
+ *
  * @see CakeTime::convertSpecifiers()
  *
  * @param string $format Format with specifiers for strftime function.
@@ -135,6 +138,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Converts given time (in server's time zone) to user's local time, given his/her timezone.
+ *
  * @see CakeTime::convert()
  *
  * @param string $serverTime UNIX timestamp
@@ -147,6 +152,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns server's offset
+ *
  * @see CakeTime::serverOffset()
  *
  * @return integer Offset
@@ -157,6 +164,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
+ *
  * @see CakeTime::fromString()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -169,6 +178,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a nicely formatted date string for given Datetime string.
+ *
  * @see CakeTime::nice()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -182,6 +193,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a formatted descriptive date string for given datetime string.
+ *
  * @see CakeTime::niceShort()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime objectp
@@ -194,6 +207,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a partial SQL string to search for all records between two dates.
+ *
  * @see CakeTime::daysAsSql()
  *
  * @param integer|string|DateTime $begin UNIX timestamp, strtotime() valid string or DateTime object
@@ -208,6 +223,9 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a partial SQL string to search for all records between two times
+ * occurring on the same day.
+ *
  * @see CakeTime::dayAsSql()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -221,6 +239,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if given datetime string is today.
+ *
  * @see CakeTime::isToday()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -233,6 +253,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if given datetime string is within this week.
+ *
  * @see CakeTime::isThisWeek()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -245,6 +267,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if given datetime string is within this month
+ *
  * @see CakeTime::isThisMonth()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -257,6 +281,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if given datetime string is within current year.
+ *
  * @see CakeTime::isThisYear()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -269,6 +295,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if given datetime string was yesterday.
+ *
  * @see CakeTime::wasYesterday()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -282,6 +310,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if given datetime string is tomorrow.
+ *
  * @see CakeTime::isTomorrow()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -294,6 +324,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns the quarter
+ *
  * @see CakeTime::toQuarter()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -306,6 +338,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a UNIX timestamp from a textual datetime description. Wrapper for PHP function strtotime().
+ *
  * @see CakeTime::toUnix()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -318,6 +352,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns a date formatted for Atom RSS feeds.
+ *
  * @see CakeTime::toAtom()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -330,6 +366,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Formats date for RSS feeds
+ *
  * @see CakeTime::toRSS()
  *
  * @param integer|string|DateTime $dateString UNIX timestamp, strtotime() valid string or DateTime object
@@ -342,6 +380,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Formats date for RSS feeds
+ *
  * @see CakeTime::timeAgoInWords()
  *
  * ## Addition options
@@ -389,6 +429,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if specified datetime was within the interval specified, else false.
+ *
  * @see CakeTime::wasWithinLast()
  *
  * @param string|integer $timeInterval the numeric value with space then time type.
@@ -403,6 +445,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns true if specified datetime is within the interval specified, else false.
+ *
  * @see CakeTime::isWithinLast()
  *
  * @param string|integer $timeInterval the numeric value with space then time type.
@@ -417,6 +461,8 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * Returns gmt as a UNIX timestamp.
+ *
  * @see CakeTime::gmt()
  *
  * @param integer|string|DateTime $string UNIX timestamp, strtotime() valid string or DateTime object
@@ -428,6 +474,21 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * 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:
+ *
+ * {{{
+ *   $this->Time->format('2012-02-15', '%m-%d-%Y'); // returns 02-15-2012
+ *   $this->Time->format('2012-02-15 23:01:01', '%c'); // returns preferred date and time based on configured locale
+ *   $this->Time->format('0000-00-00', '%d-%m-%Y', 'N/A'); // return N/A becuase an invalid date was passed
+ *   $this->Time->format('2012-02-15 23:01:01', '%c', 'N/A', 'America/New_York'); // converts passed date to timezone
+ * }}}
+ *
  * @see CakeTime::format()
  *
  * @param integer|string|DateTime $format date format string (or a UNIX timestamp, strtotime() valid string or DateTime object)
@@ -442,6 +503,9 @@ class TimeHelper extends AppHelper {
 	}
 
 /**
+ * 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 CakeTime::i18nFormat()
  *
  * @param integer|string|DateTime $date UNIX timestamp, strtotime() valid string or DateTime object

lib/Cake/View/View.php

@@ -299,16 +299,22 @@ class View extends Object {
 
 /**
  * Constant for view file type 'view'
+ *
+ * @var string
  */
 	const TYPE_VIEW = 'view';
 
 /**
  * Constant for view file type 'element'
+ *
+ * @var string
  */
 	const TYPE_ELEMENT = 'element';
 
 /**
  * Constant for view file type 'layout'
+ *
+ * @var string
  */
 	const TYPE_LAYOUT = 'layout';
 

lib/Cake/View/ViewBlock.php

@@ -28,14 +28,14 @@ class ViewBlock {
 /**
  * Append content
  *
- * @constant APPEND
+ * @var string
  */
 	const APPEND = 'append';
 
 /**
  * Prepend content
  *
- * @constant PREPEND
+ * @var string
  */
 	const PREPEND = 'prepend';