Merge pull request #6001 from deizel/3.0-global-functions

Docblock fixes to global functions (grammar and CS)

src/Collection/functions.php

@@ -16,9 +16,9 @@ use Cake\Collection\Collection;
 
 if (!function_exists('collection')) {
     /**
-     * Returns a new Cake\Collection\Collection object wrapping the passed argument
+     * Returns a new Cake\Collection\Collection object wrapping the passed argument.
      *
-     * @param \Traversable|array $items The items from which the collection will be built
+     * @param \Traversable|array $items The items from which the collection will be built.
      * @return \Cake\Collection\Collection
      */
     function collection($items)

src/Core/functions.php

@@ -16,8 +16,8 @@ use Cake\Core\Configure;
 
 if (!defined('DS')) {
     /**
- * Define DS as short form of DIRECTORY_SEPARATOR.
- */
+     * Define DS as short form of DIRECTORY_SEPARATOR.
+     */
     define('DS', DIRECTORY_SEPARATOR);
 
 }
@@ -29,10 +29,10 @@ if (!function_exists('h')) {
      * @param string|array|object $text Text to wrap through htmlspecialchars. Also works with arrays, and objects.
      *    Arrays will be mapped and have all their elements escaped. Objects will be string cast if they
      *    implement a `__toString` method. Otherwise the class name will be used.
-     * @param bool $double Encode existing html entities
+     * @param bool $double Encode existing html entities.
      * @param string $charset Character set to use when escaping. Defaults to config value in `mb_internal_encoding()`
-     * or 'UTF-8'
-     * @return string Wrapped text
+     * or 'UTF-8'.
+     * @return string Wrapped text.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#h
      */
     function h($text, $double = true, $charset = null)
@@ -80,7 +80,7 @@ if (!function_exists('pluginSplit')) {
      * @param string $name The name you want to plugin split.
      * @param bool $dotAppend Set to true if you want the plugin to have a '.' appended to it.
      * @param string $plugin Optional default plugin to use if no plugin is found. Defaults to null.
-     * @return array Array with 2 indexes. 0 => plugin name, 1 => class name
+     * @return array Array with 2 indexes. 0 => plugin name, 1 => class name.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#pluginSplit
      */
     function pluginSplit($name, $dotAppend = false, $plugin = null)
@@ -101,10 +101,10 @@ if (!function_exists('namespaceSplit')) {
     /**
      * Split the namespace from the classname.
      *
-     * Commonly used like `list($namespace, $className) = namespaceSplit($class);`
+     * Commonly used like `list($namespace, $className) = namespaceSplit($class);`.
      *
-     * @param string $class The full class name, ie `Cake\Core\App`
-     * @return array Array with 2 indexes. 0 => namespace, 1 => classname
+     * @param string $class The full class name, ie `Cake\Core\App`.
+     * @return array Array with 2 indexes. 0 => namespace, 1 => classname.
      */
     function namespaceSplit($class)
     {
@@ -119,16 +119,15 @@ if (!function_exists('namespaceSplit')) {
 
 if (!function_exists('pr')) {
     /**
-     * print_r() convenience function
+     * print_r() convenience function.
      *
      * In terminals this will act similar to using print_r() directly, when not run on cli
      * print_r() will also wrap <pre> tags around the output of given variable. Similar to debug().
      *
-     * @param mixed $var Variable to print out
+     * @param mixed $var Variable to print out.
      * @return void
      * @see debug()
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#pr
-     * @see debug()
      */
     function pr($var)
     {
@@ -147,7 +146,7 @@ if (!function_exists('pj')) {
      * In terminals this will act similar to using json_encode() with JSON_PRETTY_PRINT directly, when not run on cli
      * will also wrap <pre> tags around the output of given variable. Similar to pr().
      *
-     * @param mixed $var Variable to print out
+     * @param mixed $var Variable to print out.
      * @return void
      * @see pr()
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#pj

src/I18n/functions.php

@@ -18,9 +18,9 @@ if (!function_exists('__')) {
     /**
      * Returns a translated string if one is found; Otherwise, the submitted message.
      *
-     * @param string $singular Text to translate
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return mixed translated string
+     * @param string $singular Text to translate.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return mixed Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__
      */
     function __($singular, $args = null)
@@ -40,11 +40,11 @@ if (!function_exists('__n')) {
      * Returns correct plural form of message identified by $singular and $plural for count $count.
      * Some languages have more than one form for plural messages dependent on the count.
      *
-     * @param string $singular Singular text to translate
-     * @param string $plural Plural text
-     * @param int $count Count
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return mixed plural form of translated string
+     * @param string $singular Singular text to translate.
+     * @param string $plural Plural text.
+     * @param int $count Count.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return mixed Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__n
      */
     function __n($singular, $plural, $count, $args = null)
@@ -66,10 +66,10 @@ if (!function_exists('__d')) {
     /**
      * Allows you to override the current domain for a single message lookup.
      *
-     * @param string $domain Domain
-     * @param string $msg String to translate
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return string translated string
+     * @param string $domain Domain.
+     * @param string $msg String to translate.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return string Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__d
      */
     function __d($domain, $msg, $args = null)
@@ -89,12 +89,12 @@ if (!function_exists('__dn')) {
      * Returns correct plural form of message identified by $singular and $plural for count $count
      * from domain $domain.
      *
-     * @param string $domain Domain
-     * @param string $singular Singular string to translate
-     * @param string $plural Plural
-     * @param int $count Count
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return string plural form of translated string
+     * @param string $domain Domain.
+     * @param string $singular Singular string to translate.
+     * @param string $plural Plural.
+     * @param int $count Count.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return string Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dn
      */
     function __dn($domain, $singular, $plural, $count, $args = null)
@@ -116,12 +116,12 @@ if (!function_exists('__x')) {
     /**
      * Returns a translated string if one is found; Otherwise, the submitted message.
      * The context is a unique identifier for the translations string that makes it unique
-     * for in the same domain.
+     * within the same domain.
      *
-     * @param string $context Context of the text
-     * @param string $singular Text to translate
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return mixed translated string
+     * @param string $context Context of the text.
+     * @param string $singular Text to translate.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return mixed Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__
      */
     function __x($context, $singular, $args = null)
@@ -141,14 +141,14 @@ if (!function_exists('__xn')) {
      * Returns correct plural form of message identified by $singular and $plural for count $count.
      * Some languages have more than one form for plural messages dependent on the count.
      * The context is a unique identifier for the translations string that makes it unique
-     * for in the same domain.
+     * within the same domain.
      *
-     * @param string $context Context of the text
-     * @param string $singular Singular text to translate
-     * @param string $plural Plural text
-     * @param int $count Count
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return mixed plural form of translated string
+     * @param string $context Context of the text.
+     * @param string $singular Singular text to translate.
+     * @param string $plural Plural text.
+     * @param int $count Count.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return mixed Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__xn
      */
     function __xn($context, $singular, $plural, $count, $args = null)
@@ -170,13 +170,13 @@ if (!function_exists('__dx')) {
     /**
      * Allows you to override the current domain for a single message lookup.
      * The context is a unique identifier for the translations string that makes it unique
-     * for in the same domain.
+     * within the same domain.
      *
-     * @param string $domain Domain
-     * @param string $context Context of the text
-     * @param string $msg String to translate
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return string translated string
+     * @param string $domain Domain.
+     * @param string $context Context of the text.
+     * @param string $msg String to translate.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return string Translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dx
      */
     function __dx($domain, $context, $msg, $args = null)
@@ -199,15 +199,15 @@ if (!function_exists('__dxn')) {
      * Returns correct plural form of message identified by $singular and $plural for count $count.
      * Allows you to override the current domain for a single message lookup.
      * The context is a unique identifier for the translations string that makes it unique
-     * for in the same domain.
+     * within the same domain.
      *
-     * @param string $domain Domain
-     * @param string $context Context of the text
-     * @param string $singular Singular text to translate
-     * @param string $plural Plural text
-     * @param int $count Count
-     * @param mixed $args Array with arguments or multiple arguments in function
-     * @return mixed plural form of translated string
+     * @param string $domain Domain.
+     * @param string $context Context of the text.
+     * @param string $singular Singular text to translate.
+     * @param string $plural Plural text.
+     * @param int $count Count.
+     * @param mixed $args Array with arguments or multiple arguments in function.
+     * @return mixed Plural form of translated string.
      * @link http://book.cakephp.org/3.0/en/core-libraries/global-constants-and-functions.html#__dxn
      */
     function __dxn($domain, $context, $singular, $plural, $count, $args = null)