Merge branch 'master' into 2.6

lib/Cake/Controller/Component/Auth/DigestAuthenticate.php

@@ -156,7 +156,7 @@ class DigestAuthenticate extends BasicAuthenticate {
  * Parse the digest authentication headers and split them up.
  *
  * @param string $digest The raw digest authentication headers.
- * @return array An array of digest authentication headers
+ * @return array|null An array of digest authentication headers
  */
 	public function parseAuthData($digest) {
 		if (substr($digest, 0, 7) === 'Digest ') {

lib/Cake/Controller/Component/AuthComponent.php

@@ -648,7 +648,7 @@ class AuthComponent extends Component {
  * cookies + sessions will be used.
  *
  * @param string $key field to retrieve. Leave null to get entire User record
- * @return mixed User record. or null if no user is logged in.
+ * @return array|null User record. or null if no user is logged in.
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/authentication.html#accessing-the-logged-in-user
  */
 	public static function user($key = null) {

lib/Cake/Controller/Component/CookieComponent.php

@@ -262,7 +262,7 @@ class CookieComponent extends Component {
  * $this->Cookie->read(Name.key);
  *
  * @param string $key Key of the value to be obtained. If none specified, obtain map key => values
- * @return string or null, value for specified key
+ * @return string|null Value for specified key
  * @link http://book.cakephp.org/2.0/en/core-libraries/components/cookie.html#CookieComponent::read
  */
 	public function read($key = null) {

lib/Cake/Controller/Component/EmailComponent.php

@@ -405,7 +405,7 @@ class EmailComponent extends Component {
  * Find the specified attachment in the list of file paths
  *
  * @param string $attachment Attachment file name to find
- * @return string Path to located file
+ * @return string|null Path to located file
  */
 	protected function _findFiles($attachment) {
 		if (file_exists($attachment)) {

lib/Cake/Controller/Component/RequestHandlerComponent.php

@@ -162,7 +162,7 @@ class RequestHandlerComponent extends Component {
 		$accepts = $this->response->mapType($accept);
 		$preferedTypes = current($accepts);
 		if (array_intersect($preferedTypes, array('html', 'xhtml'))) {
-			return null;
+			return;
 		}
 
 		$extensions = Router::extensions();
@@ -724,7 +724,7 @@ class RequestHandlerComponent extends Component {
  * Maps a content type alias back to its mime-type(s)
  *
  * @param string|array $alias String alias to convert back into a content type. Or an array of aliases to map.
- * @return string Null on an undefined alias. String value of the mapped alias type. If an
+ * @return string|null Null on an undefined alias. String value of the mapped alias type. If an
  *   alias maps to more than one content type, the first one will be returned.
  */
 	public function mapAlias($alias) {

lib/Cake/Controller/Component/SecurityComponent.php

@@ -355,7 +355,7 @@ class SecurityComponent extends Component {
  * Check if HTTP methods are required
  *
  * @param Controller $controller Instantiating controller
- * @return bool true if $method is required
+ * @return bool|null True if $method is required
  */
 	protected function _methodsRequired(Controller $controller) {
 		foreach (array('Post', 'Get', 'Put', 'Delete') as $method) {
@@ -378,7 +378,7 @@ class SecurityComponent extends Component {
  * Check if access requires secure connection
  *
  * @param Controller $controller Instantiating controller
- * @return bool true if secure connection required
+ * @return bool|null True if secure connection required
  */
 	protected function _secureRequired(Controller $controller) {
 		if (is_array($this->requireSecure) && !empty($this->requireSecure)) {
@@ -399,7 +399,7 @@ class SecurityComponent extends Component {
  * Check if authentication is required
  *
  * @param Controller $controller Instantiating controller
- * @return bool true if authentication required
+ * @return bool|null True if authentication required
  */
 	protected function _authRequired(Controller $controller) {
 		if (is_array($this->requireAuth) && !empty($this->requireAuth) && !empty($this->request->data)) {

lib/Cake/Controller/Controller.php

@@ -1017,7 +1017,7 @@ class Controller extends Object implements CakeEventListener {
  * @param string $bool SQL boolean operator: AND, OR, XOR, etc.
  * @param bool $exclusive If true, and $op is an array, fields not included in $op will not be
  *        included in the returned conditions
- * @return array An array of model conditions
+ * @return array|null An array of model conditions
  * @deprecated 3.0.0 Will be removed in 3.0.
  */
 	public function postConditions($data = array(), $op = null, $bool = 'AND', $exclusive = false) {

lib/Cake/Core/App.php

@@ -575,7 +575,7 @@ class App {
  * Returns the package name where a class was defined to be located at
  *
  * @param string $className name of the class to obtain the package name from
- * @return string package name or null if not declared
+ * @return string|null Package name, or null if not declared
  * @link http://book.cakephp.org/2.0/en/core-utility-libraries/app.html#App::location
  */
 	public static function location($className) {

lib/Cake/I18n/Multibyte.php

@@ -824,7 +824,7 @@ class Multibyte {
  *
  * @param int $char decimal value of character
  * @param string $type Type 'lower' or 'upper'. Defaults to 'lower'.
- * @return array
+ * @return array|null
  */
 	protected static function _find($char, $type = 'lower') {
 		$found = array();

lib/Cake/Model/Behavior/AclBehavior.php

@@ -73,7 +73,7 @@ class AclBehavior extends ModelBehavior {
  * @param Model $model Model using this behavior.
  * @param string|array|Model $ref Array with 'model' and 'foreign_key', model object, or string value
  * @param string $type Only needed when Acl is set up as 'both', specify 'Aro' or 'Aco' to get the correct node
- * @return array
+ * @return array|null
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/acl.html#node
  */
 	public function node(Model $model, $ref = null, $type = null) {

lib/Cake/Model/Behavior/TreeBehavior.php

@@ -443,7 +443,7 @@ class TreeBehavior extends ModelBehavior {
  * @param int|string $id The ID of the record to read
  * @param string|array $fields Either a single string of a field name, or an array of field names
  * @param int $recursive The number of levels deep to fetch associated records
- * @return array Array of nodes from top most parent to current node
+ * @return array|null Array of nodes from top most parent to current node
  * @link http://book.cakephp.org/2.0/en/core-libraries/behaviors/tree.html#TreeBehavior::getPath
  */
 	public function getPath(Model $Model, $id = null, $fields = null, $recursive = null) {

lib/Cake/Model/ConnectionManager.php

@@ -126,7 +126,7 @@ class ConnectionManager {
  * Gets a DataSource name from an object reference.
  *
  * @param DataSource $source DataSource object
- * @return string Datasource name, or null if source is not present
+ * @return string|null Datasource name, or null if source is not present
  *    in the ConnectionManager.
  */
 	public static function getSourceName($source) {
@@ -145,8 +145,8 @@ class ConnectionManager {
  * Loads the DataSource class for the given connection name
  *
  * @param string|array $connName A string name of the connection, as defined in app/Config/database.php,
- *                        or an array containing the filename (without extension) and class name of the object,
+ *    or an array containing the filename (without extension) and class name of the object,
- *                        to be found in app/Model/Datasource/ or lib/Cake/Model/Datasource/.
+ *    to be found in app/Model/Datasource/ or lib/Cake/Model/Datasource/.
  * @return bool True on success, null on failure or false if the class is already loaded
  * @throws MissingDatasourceException
  */
@@ -184,10 +184,10 @@ class ConnectionManager {
 	}
 
 /**
- * Return a list of connections
+ * Returns a list of connections
  *
  * @return array An associative array of elements where the key is the connection name
- *               (as defined in Connections), and the value is an array with keys 'filename' and 'classname'.
+ *    (as defined in Connections), and the value is an array with keys 'filename' and 'classname'.
  */
 	public static function enumConnectionObjects() {
 		if (empty(self::$_init)) {
@@ -201,7 +201,7 @@ class ConnectionManager {
  *
  * @param string $name The DataSource name
  * @param array $config The DataSource configuration settings
- * @return DataSource A reference to the DataSource object, or null if creation failed
+ * @return DataSource|null A reference to the DataSource object, or null if creation failed
  */
 	public static function create($name = '', $config = array()) {
 		if (empty(self::$_init)) {

lib/Cake/Model/Datasource/DataSource.php

@@ -90,7 +90,7 @@ class DataSource extends Object {
  * Caches/returns cached results for child instances
  *
  * @param mixed $data Unused in this class.
- * @return array Array of sources available in this datasource.
+ * @return array|null Array of sources available in this datasource.
  */
 	public function listSources($data = null) {
 		if ($this->cacheSources === false) {
@@ -117,7 +117,7 @@ class DataSource extends Object {
  * Returns a Model description (metadata) or null if none found.
  *
  * @param Model|string $model The model to describe.
- * @return array Array of Metadata for the $model
+ * @return array|null Array of Metadata for the $model
  */
 	public function describe($model) {
 		if ($this->cacheSources === false) {
@@ -407,14 +407,14 @@ class DataSource extends Object {
 /**
  * Returns the schema name. Override this in subclasses.
  *
- * @return string schema name
+ * @return string|null The schema name
  */
 	public function getSchemaName() {
 		return null;
 	}
 
 /**
- * Closes a connection. Override in subclasses
+ * Closes a connection. Override in subclasses.
  *
  * @return bool
  */

lib/Cake/Model/Model.php

@@ -1381,7 +1381,7 @@ class Model extends Object implements CakeEventListener {
  * $field => keys(type, null, default, key, length, extra)
  *
  * @param bool|string $field Set to true to reload schema, or a string to return a specific field
- * @return array Array of table metadata
+ * @return array|null Array of table metadata
  */
 	public function schema($field = false) {
 		if ($this->useTable !== false && (!is_array($this->_schema) || $field === true)) {
@@ -2972,7 +2972,7 @@ class Model extends Object implements CakeEventListener {
  *
  * @param string $type Type of find operation (all / first / count / neighbors / list / threaded)
  * @param array $query Option fields (conditions / fields / joins / limit / offset / order / page / group / callbacks)
- * @return array Array of records, or Null on failure.
+ * @return array|null Array of records, or Null on failure.
  * @link http://book.cakephp.org/2.0/en/models/retrieving-your-data.html
  */
 	public function find($type = 'first', $query = array()) {
@@ -3031,7 +3031,7 @@ class Model extends Object implements CakeEventListener {
  *
  * @param string $type Type of find operation (all / first / count / neighbors / list / threaded)
  * @param array $query Option fields (conditions / fields / joins / limit / offset / order / page / group / callbacks)
- * @return array Query array or null if it could not be build for some reasons
+ * @return array|null Query array or null if it could not be build for some reasons
  * @see Model::find()
  */
 	public function buildQuery($type = 'first', $query = array()) {
@@ -3650,7 +3650,7 @@ class Model extends Object implements CakeEventListener {
  * Gets all the models with which this model is associated.
  *
  * @param string $type Only result associations of this type
- * @return array Associations
+ * @return array|null Associations
  */
 	public function getAssociated($type = null) {
 		if (!$type) {

lib/Cake/Model/ModelValidator.php

@@ -318,7 +318,7 @@ class ModelValidator implements ArrayAccess, IteratorAggregate, Countable {
  * params are passed then it returns an array with all CakeValidationSet objects for each field
  *
  * @param string $name [optional] The fieldname to fetch. Defaults to null.
- * @return CakeValidationSet|array
+ * @return CakeValidationSet|array|null
  */
 	public function getField($name = null) {
 		$this->_parseRules();

lib/Cake/Model/Validator/CakeValidationRule.php

@@ -300,7 +300,7 @@ class CakeValidationRule {
  * Returns passed options for this rule
  *
  * @param string|int $key Array index
- * @return array
+ * @return array|null
  */
 	public function getOptions($key) {
 		if (!isset($this->_passedOptions[$key])) {

lib/Cake/Network/CakeSocket.php

@@ -238,7 +238,7 @@ class CakeSocket {
 /**
  * Get the last error as a string.
  *
- * @return string Last error
+ * @return string|null Last error
  */
 	public function lastError() {
 		if (!empty($this->lastError)) {

lib/Cake/Utility/Set.php

@@ -97,7 +97,7 @@ class Set {
  *
  * @param string $class A class name of the type of object to map to
  * @param string $tmp A temporary class name used as $class if $class is an array
- * @return object Hierarchical object
+ * @return object|null Hierarchical object
  * @link http://book.cakephp.org/2.0/en/core-utility-libraries/set.html#Set::map
  */
 	public static function map($class = 'stdClass', $tmp = 'stdClass') {

lib/Cake/View/Helper.php

@@ -406,7 +406,7 @@ class Helper extends Object {
  * content is the best way to prevent all possible attacks.
  *
  * @param string|array $output Either an array of strings to clean or a single string to clean.
- * @return string|array cleaned content for output
+ * @return string|array|null Cleaned content for output
  * @deprecated 3.0.0 This method will be removed in 3.0
  */
 	public function clean($output) {

lib/Cake/View/Helper/FormHelper.php

@@ -141,7 +141,7 @@ class FormHelper extends AppHelper {
  * or get an already created instance of the model
  *
  * @param string $model Model name.
- * @return Model model instance
+ * @return Model|null Model instance
  */
 	protected function _getModel($model) {
 		$object = null;

lib/Cake/View/Helper/HtmlHelper.php

@@ -198,7 +198,7 @@ class HtmlHelper extends AppHelper {
  *  - xhtml11: XHTML1.1.
  *
  * @param string $type Doctype to use.
- * @return string Doctype string
+ * @return string|null Doctype string
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#HtmlHelper::docType
  */
 	public function docType($type = 'html5') {
@@ -628,7 +628,6 @@ class HtmlHelper extends AppHelper {
 		$options += array('safe' => true, 'inline' => true);
 		$this->_scriptBlockOptions = $options;
 		ob_start();
-		return null;
 	}
 
 /**
@@ -690,7 +689,7 @@ class HtmlHelper extends AppHelper {
  * @param string $separator Text to separate crumbs.
  * @param string|array|bool $startText This will be the first crumb, if false it defaults to first crumb in array. Can
  *   also be an array, see above for details.
- * @return string Composed bread crumbs
+ * @return string|null Composed bread crumbs
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper
  */
 	public function getCrumbs($separator = '»', $startText = false) {
@@ -724,7 +723,7 @@ class HtmlHelper extends AppHelper {
  * @param array $options Array of html attributes to apply to the generated list elements.
  * @param string|array|bool $startText This will be the first crumb, if false it defaults to first crumb in array. Can
  *   also be an array, see `HtmlHelper::getCrumbs` for details.
- * @return string breadcrumbs html list
+ * @return string|null breadcrumbs html list
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/html.html#creating-breadcrumb-trails-with-htmlhelper
  */
 	public function getCrumbList($options = array(), $startText = false) {

lib/Cake/View/Helper/PaginatorHelper.php

@@ -120,7 +120,7 @@ class PaginatorHelper extends AppHelper {
  * Gets the current paging parameters from the resultset for the given model
  *
  * @param string $model Optional model name. Uses the default if none is specified.
- * @return array The array of paging parameters for the paginated resultset.
+ * @return array|null The array of paging parameters for the paginated resultset.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/paginator.html#PaginatorHelper::params
  */
 	public function params($model = null) {
@@ -207,7 +207,7 @@ class PaginatorHelper extends AppHelper {
  *
  * @param string $model Optional model name. Uses the default if none is specified.
  * @param array $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
+ * @return string|null The name of the key by which the recordset is being sorted, or
  *  null if the results are not currently sorted.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/paginator.html#PaginatorHelper::sortKey
  */
@@ -481,7 +481,7 @@ class PaginatorHelper extends AppHelper {
  * @param array $options Options list.
  * @param string $disabledTitle Disabled link title.
  * @param array $disabledOptions Disabled link options.
- * @return string
+ * @return string|null
  */
 	protected function _pagingLink($which, $title = null, $options = array(), $disabledTitle = null, $disabledOptions = array()) {
 		$check = 'has' . $which;
@@ -594,7 +594,7 @@ class PaginatorHelper extends AppHelper {
 /**
  * Gets the default model of the paged sets
  *
- * @return string Model name or null if the pagination isn't initialized.
+ * @return string|null Model name or null if the pagination isn't initialized.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/paginator.html#PaginatorHelper::defaultModel
  */
 	public function defaultModel() {
@@ -707,7 +707,7 @@ class PaginatorHelper extends AppHelper {
  * - `currentTag` Tag to use for current page number, defaults to null
  *
  * @param array $options Options for the numbers, (before, after, model, modulus, separator)
- * @return string numbers string.
+ * @return string|bool numbers string.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/paginator.html#PaginatorHelper::numbers
  */
 	public function numbers($options = array()) {
@@ -849,7 +849,7 @@ class PaginatorHelper extends AppHelper {
  * @param string|int $first if string use as label for the link. If numeric, the number of page links
  *   you want at the beginning of the range.
  * @param array $options An array of options.
- * @return string numbers string.
+ * @return string|bool numbers string.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/paginator.html#PaginatorHelper::first
  */
 	public function first($first = '<< first', $options = array()) {
@@ -912,7 +912,7 @@ class PaginatorHelper extends AppHelper {
  *
  * @param string|int $last if string use as label for the link, if numeric print page numbers
  * @param array $options Array of options
- * @return string numbers string.
+ * @return string|bool numbers string.
  * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/paginator.html#PaginatorHelper::last
  */
 	public function last($last = 'last >>', $options = array()) {

lib/Cake/View/Helper/TimeHelper.php

@@ -83,7 +83,7 @@ class TimeHelper extends AppHelper {
  * Magic isset check for deprecated attributes.
  *
  * @param string $name Name of the attribute to check.
- * @return bool
+ * @return bool|null
  */
 	public function __isset($name) {
 		if (isset($this->{$name})) {

lib/Cake/basics.php

@@ -160,7 +160,7 @@ if (!function_exists('sortByKey')) {
  * @param string $sortBy Sort by this key
  * @param string $order Sort order asc/desc (ascending or descending).
  * @param int $type Type of sorting to perform
- * @return mixed Sorted array
+ * @return array|null Sorted array, or null if not an array.
  * @link http://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#sortByKey
  */
 	function sortByKey(&$array, $sortBy, $order = 'asc', $type = SORT_NUMERIC) {
@@ -315,7 +315,7 @@ if (!function_exists('env')) {
  * environment information.
  *
  * @param string $key Environment variable name.
- * @return string Environment variable setting.
+ * @return string|bool|null Environment variable setting.
  * @link http://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#env
  */
 	function env($key) {