From a1219e38e9553fb83ede72d3539964356d3f0b2a Mon Sep 17 00:00:00 2001 From: Ryan Cramer Date: Thu, 17 Nov 2016 15:20:09 -0500 Subject: [PATCH] Some phpdoc updates in a few classes, plus fix a bug in the $config->paths() method --- wire/core/Config.php | 2 +- wire/core/Page.php | 2 +- wire/core/Pages.php | 4 ++-- wire/core/Sanitizer.php | 20 ++++++++++---------- wire/core/WireArray.php | 12 +++++++----- wire/core/WireCache.php | 32 +++++++++++++++++++------------- wire/core/WireDateTime.php | 2 +- 7 files changed, 41 insertions(+), 33 deletions(-) diff --git a/wire/core/Config.php b/wire/core/Config.php index 0e09b187..c8e650e8 100644 --- a/wire/core/Config.php +++ b/wire/core/Config.php @@ -215,7 +215,7 @@ class Config extends WireData { * @return null|string * */ - public function paths($for) { return $this->paths($for); } + public function paths($for) { return $this->path($for); } /** * List of config keys that are also exported in javascript diff --git a/wire/core/Page.php b/wire/core/Page.php index 4c1deae4..ead74419 100644 --- a/wire/core/Page.php +++ b/wire/core/Page.php @@ -2271,7 +2271,7 @@ class Page extends WireData implements \Countable, WireMatchable { * ~~~~~ * * #pw-group-manipulation - * #pw-links [Blog post about setAndSave](https://processwire.com/blog/posts/processwire-2.6.9-core-updates-and-new-procache-version/#new-page-gt-setandsave-method) + * #pw-links [Blog post about setAndSave](https://processwire.com/blog/posts/processwire-2.6.9-core-updates-and-new-procache-version/) * * @param array|string $key Field or property name to set, or array of one or more ['property' => $value]. * @param string|int|bool|object $value Value to set, or omit if you provided an array in first argument. diff --git a/wire/core/Pages.php b/wire/core/Pages.php index 344d1c39..5f5ce2a7 100644 --- a/wire/core/Pages.php +++ b/wire/core/Pages.php @@ -278,8 +278,8 @@ class Pages extends Wire { * * #pw-group-retrieval * - * @param $selector - * @param array $options + * @param string|array|Selectors $selector Selector to find pages + * @param array $options Options to modify behavior. See `Pages::find()` $options argument for details. * @return PageArray * @since 3.0.19 * @see Pages::find(), Pages::findOne() diff --git a/wire/core/Sanitizer.php b/wire/core/Sanitizer.php index f610f9fb..669a0e04 100644 --- a/wire/core/Sanitizer.php +++ b/wire/core/Sanitizer.php @@ -914,15 +914,15 @@ class Sanitizer extends Wire { * #pw-group-strings * * @param string $value String value to sanitize - * @param array $options Options to modify default behavior: - * - `maxLength` (int): maximum characters allowed, or 0=no max (default=255). - * - `maxBytes` (int): maximum bytes allowed (default=0, which implies maxLength*4). - * - `stripTags` (bool): strip markup tags? (default=true). - * - `allowableTags` (string): markup tags that are allowed, if stripTags is true (use same format as for PHP's `strip_tags()` function. - * - `multiLine` (bool): allow multiple lines? if false, then $newlineReplacement below is applicable (default=false). - * - `newlineReplacement` (string): character to replace newlines with, OR specify boolean TRUE to remove extra lines (default=" "). - * - `inCharset` (string): input character set (default="UTF-8"). - * - `outCharset` (string): output character set (default="UTF-8"). + * @param array $options Options to modify default behavior: + * - `maxLength` (int): maximum characters allowed, or 0=no max (default=255). + * - `maxBytes` (int): maximum bytes allowed (default=0, which implies maxLength*4). + * - `stripTags` (bool): strip markup tags? (default=true). + * - `allowableTags` (string): markup tags that are allowed, if stripTags is true (use same format as for PHP's `strip_tags()` function. + * - `multiLine` (bool): allow multiple lines? if false, then $newlineReplacement below is applicable (default=false). + * - `newlineReplacement` (string): character to replace newlines with, OR specify boolean TRUE to remove extra lines (default=" "). + * - `inCharset` (string): input character set (default="UTF-8"). + * - `outCharset` (string): output character set (default="UTF-8"). * @return string * @see Sanitizer::textarea() * @@ -1007,7 +1007,7 @@ class Sanitizer extends Wire { * * @param string $value String value to sanitize * @param array $options Options to modify default behavior - * - `maxLength` (int): maximum characters allowed, or 0=no max (default=16384 or 16kb). + * - `maxLength` (int): maximum characters allowed, or 0=no max (default=16384 or 16kb). * - `maxBytes` (int): maximum bytes allowed (default=0, which implies maxLength*3 or 48kb). * - `stripTags` (bool): strip markup tags? (default=true). * - `allowableTags` (string): markup tags that are allowed, if stripTags is true (use same format as for PHP's `strip_tags()` function. diff --git a/wire/core/WireArray.php b/wire/core/WireArray.php index 7c86ce0f..33016768 100644 --- a/wire/core/WireArray.php +++ b/wire/core/WireArray.php @@ -1900,6 +1900,7 @@ class WireArray extends Wire implements \IteratorAggregate, \ArrayAccess, \Count * - `append` (string): String to append to result. Ignored if result is blank. * - Please note that if delimiter is omitted, $options becomes the second argument. * @return string + * @see WireArray::each(), WireArray::explode() * */ public function implode($delimiter, $property = '', array $options = array()) { @@ -1966,6 +1967,7 @@ class WireArray extends Wire implements \IteratorAggregate, \ArrayAccess, \Count * - `getMethod` (string): Method to call on each item to retrieve $property (default = "get") * - `key` (string|null): Property of Wire objects to use for key of array, or omit (null) for non-associative array (default). * @return array + * @see WireArray::each(), WireArray::implode() * */ public function explode($property, array $options = array()) { @@ -2046,11 +2048,10 @@ class WireArray extends Wire implements \IteratorAggregate, \ArrayAccess, \Count * @param string|null $key Name of data property you want to get or set. Omit to get all data properties. * @param mixed|null $value Value of data property you want to set. Omit when getting properties. * @return $this|mixed|null Returns one of the following, depending on specified arguments: - * - `mixed` when getting a single property: whatever you set is what you will get back. - * - `null` if the property you are trying to get does not exist in the data. - * - `$this` reference to this WireArray if you were setting a value. - * - `array` of all data if you specified no arguments. - * + * - `mixed` when getting a single property: whatever you set is what you will get back. + * - `null` if the property you are trying to get does not exist in the data. + * - `$this` reference to this WireArray if you were setting a value. + * - `array` of all data if you specified no arguments. * */ public function data($key = null, $value = null) { @@ -2202,6 +2203,7 @@ class WireArray extends Wire implements \IteratorAggregate, \ArrayAccess, \Count * (if using option #3 in arguments). * - `array` (4): Returns an array of associative arrays containing the property values for each item * you requested (if using option #4 in arguments). + * @see WireArray::implode(), WireArray::explode() * */ public function each($func = null) { diff --git a/wire/core/WireCache.php b/wire/core/WireCache.php index 60ccb0d6..c87ab615 100644 --- a/wire/core/WireCache.php +++ b/wire/core/WireCache.php @@ -337,13 +337,13 @@ class WireCache extends Wire { * * @param string $name Name of cache, can be any string up to 255 chars * @param string|array|PageArray $data Data that you want to cache - * @param int|Page $expire Lifetime of this cache, in seconds - * ...or specify: WireCache::expireHourly, WireCache::expireDaily, WireCache::expireWeekly, WireCache::expireMonthly - * ...or specify the future date you want it to expire (as unix timestamp or any strtotime compatible date format) - * ...or provide a Page object to expire when any page using that template is saved. - * ...or specify: WireCache::expireNever to prevent expiration. - * ...or specify: WireCache::expireSave to expire when any page or template is saved. - * ...or specify: Selector string matching pages that, when saved, expire the cache. + * @param int|Page $expire Lifetime of this cache, in seconds, OR one of the following: + * - Specify one of the `WireCache::expire*` constants. + * - Specify the future date you want it to expire (as unix timestamp or any strtotime compatible date format) + * - Provide a Page object to expire when any page using that template is saved. + * - Specify `WireCache::expireNever` to prevent expiration. + * - Specify `WireCache::expireSave` to expire when any page or template is saved. + * - Specify selector string matching pages that, when saved, expire the cache. * @return bool Returns true if cache was successful, false if not * @throws WireException if given uncachable data * @@ -401,11 +401,17 @@ class WireCache extends Wire { /** * Same as save() except with namespace * - * @param string|object $ns Namespace - * @param $name - * @param $data - * @param int $expire - * @return bool + * @param string|object $ns Namespace for cache + * @param string $name Name of cache, can be any string up to 255 chars + * @param string|array|PageArray $data Data that you want to cache + * @param int|Page $expire Lifetime of this cache, in seconds, OR one of the following: + * - Specify one of the `WireCache::expire*` constants. + * - Specify the future date you want it to expire (as unix timestamp or any strtotime compatible date format) + * - Provide a Page object to expire when any page using that template is saved. + * - Specify `WireCache::expireNever` to prevent expiration. + * - Specify `WireCache::expireSave` to expire when any page or template is saved. + * - Specify selector string matching pages that, when saved, expire the cache. + * @return bool Returns true if cache was successful, false if not * */ public function saveFor($ns, $name, $data, $expire = self::expireDaily) { @@ -521,7 +527,7 @@ class WireCache extends Wire { /** * Delete the cache identified by $name within given namespace ($ns) * - * @param string $ns + * @param string $ns Namespace of cache * @param string $name If none specified, all for $ns are deleted * @return bool True on success, false on failure * diff --git a/wire/core/WireDateTime.php b/wire/core/WireDateTime.php index 2032bdac..c4615cd4 100644 --- a/wire/core/WireDateTime.php +++ b/wire/core/WireDateTime.php @@ -365,7 +365,7 @@ class WireDateTime extends Wire { * * ~~~~~~ * // Output the current date/time in relative format - * echo $date->formatDate('relative'); + * echo $datetime->date('relative'); * ~~~~~~ * * @param string|int $format Use one of the following: