Docs: First pass at some inline docs fixes mostly made by PHPCBF.

See #49572, #50744

git-svn-id: https://develop.svn.wordpress.org/trunk@48586 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
John Blackbourn
2020-07-23 19:59:16 +00:00
parent b6046636f0
commit 285fa03b3a
41 changed files with 154 additions and 151 deletions
+2 -2
View File
@@ -1241,8 +1241,8 @@ function is_admin_bar_showing() {
* @access private
*
* @param string $context Context of this preference check. Defaults to 'front'. The 'admin'
* preference is no longer used.
* @param int $user Optional. ID of the user to check, defaults to 0 for current user.
* preference is no longer used.
* @param int $user Optional. ID of the user to check, defaults to 0 for current user.
* @return bool Whether the admin bar should be showing for this user.
*/
function _get_admin_bar_pref( $context = 'front', $user = 0 ) {
+1 -1
View File
@@ -22,7 +22,7 @@
* @since 2.1.0
* @access private
*
* @param array $bookmarks List of bookmarks to traverse.
* @param array $bookmarks List of bookmarks to traverse.
* @param string|array $args {
* Optional. Bookmarks arguments.
*
+7 -6
View File
@@ -14,9 +14,10 @@
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int|stdClass $bookmark
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* an stdClass object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $filter Optional. How to sanitize bookmark fields. Default 'raw'.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond
* to an stdClass object, an associative array, or a numeric array, respectively.
* Default OBJECT.
* @param string $filter Optional. How to sanitize bookmark fields. Default 'raw'.
* @return array|object|null Type returned depends on $output value.
*/
function get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' ) {
@@ -68,9 +69,9 @@ function get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' ) {
*
* @since 2.3.0
*
* @param string $field The name of the data field to return
* @param int $bookmark The bookmark ID to get field
* @param string $context Optional. The context of how the field will be used.
* @param string $field The name of the data field to return.
* @param int $bookmark The bookmark ID to get field.
* @param string $context Optional. The context of how the field will be used.
* @return string|WP_Error
*/
function get_bookmark_field( $field, $bookmark, $context = 'display' ) {
+6 -6
View File
@@ -111,12 +111,12 @@ function wp_cache_flush() {
* @see WP_Object_Cache::get()
* @global WP_Object_Cache $wp_object_cache Object cache global instance.
*
* @param int|string $key The key under which the cache contents are stored.
* @param string $group Optional. Where the cache contents are grouped. Default empty.
* @param bool $force Optional. Whether to force an update of the local cache
* from the persistent cache. Default false.
* @param bool $found Optional. Whether the key was found in the cache (passed by reference).
* Disambiguates a return of false, a storable value. Default null.
* @param int|string $key The key under which the cache contents are stored.
* @param string $group Optional. Where the cache contents are grouped. Default empty.
* @param bool $force Optional. Whether to force an update of the local cache
* from the persistent cache. Default false.
* @param bool $found Optional. Whether the key was found in the cache (passed by reference).
* Disambiguates a return of false, a storable value. Default null.
* @return mixed|false The cache contents on success, false on failure to retrieve contents.
*/
function wp_cache_get( $key, $group = '', $force = false, &$found = null ) {
+3 -3
View File
@@ -35,8 +35,8 @@
* @global WP $wp Current WordPress environment instance.
*
* @param string $requested_url Optional. The URL that was requested, used to
* figure if redirect is needed.
* @param bool $do_redirect Optional. Redirect to the new URL.
* figure if redirect is needed.
* @param bool $do_redirect Optional. Redirect to the new URL.
* @return string|void The string of the URL, if redirect needed.
*/
function redirect_canonical( $requested_url = null, $do_redirect = true ) {
@@ -782,7 +782,7 @@ function redirect_canonical( $requested_url = null, $do_redirect = true ) {
* @access private
*
* @param string $query_string
* @param array $args_to_check
* @param array $args_to_check
* @param string $url
* @return string The altered query string
*/
+12 -11
View File
@@ -126,8 +126,8 @@ function get_the_category_by_ID( $cat_ID ) { // phpcs:ignore WordPress.NamingCon
*
* @param string $separator Optional. Separator between the categories. By default, the links are placed
* in an unordered list. An empty string will result in the default behavior.
* @param string $parents Optional. How to display the parents.
* @param int $post_id Optional. Post ID to retrieve categories.
* @param string $parents Optional. How to display the parents.
* @param int $post_id Optional. Post ID to retrieve categories.
* @return string
*/
function get_the_category_list( $separator = '', $parents = '', $post_id = false ) {
@@ -238,9 +238,10 @@ function get_the_category_list( $separator = '', $parents = '', $post_id = false
* Conditional Tags} article in the Theme Developer Handbook.
*
* @since 1.2.0
* @since 2.7.0 The `$post` parameter was added.
*
* @param int|string|array $category Category ID, name or slug, or array of said.
* @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0)
* @param int|object $post Optional. Post to check instead of the current post.
* @return bool True if the current post is in any of the given categories.
*/
function in_category( $category, $post = null ) {
@@ -258,8 +259,8 @@ function in_category( $category, $post = null ) {
*
* @param string $separator Optional. Separator between the categories. By default, the links are placed
* in an unordered list. An empty string will result in the default behavior.
* @param string $parents Optional. How to display the parents.
* @param int $post_id Optional. Post ID to retrieve categories.
* @param string $parents Optional. How to display the parents.
* @param int $post_id Optional. Post ID to retrieve categories.
*/
function the_category( $separator = '', $parents = '', $post_id = false ) {
echo get_the_category_list( $separator, $parents, $post_id );
@@ -1161,10 +1162,10 @@ function get_the_tags( $id = 0 ) {
*
* @since 2.3.0
*
* @param string $before Optional. Before tags.
* @param string $sep Optional. Between tags.
* @param string $after Optional. After tags.
* @param int $id Optional. Post ID. Defaults to the current post.
* @param string $before Optional. String to use before tags.
* @param string $sep Optional. String to use between the tags.
* @param string $after Optional. String to use after tags.
* @param int $id Optional. Post ID. Defaults to the current post.
* @return string|false|WP_Error A list of tags on success, false if there are no terms, WP_Error on failure.
*/
function get_the_tag_list( $before = '', $sep = '', $after = '', $id = 0 ) {
@@ -1333,8 +1334,8 @@ function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = ''
*
* @since 4.8.0
*
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy name.
* @param int $term_id Term ID.
* @param string $taxonomy Taxonomy name.
* @param string|array $args {
* Array of optional arguments.
*
+4 -4
View File
@@ -81,10 +81,10 @@ function get_categories( $args = '' ) {
* @since 1.5.1
*
* @param int|object $category Category ID or Category row object
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N,
* which correspond to a WP_Term object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. How to sanitize category fields. Default 'raw'.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N,
* which correspond to a WP_Term object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. How to sanitize category fields. Default 'raw'.
* @return object|array|WP_Error|null Category data in type defined by $output parameter.
* WP_Error if $category is empty, null if it does not exist.
*/
+7 -7
View File
@@ -509,8 +509,8 @@ class WP_Http {
*
* @since 3.2.0
*
* @param array $args Request arguments.
* @param string $url URL to Request.
* @param array $args Request arguments.
* @param string $url URL to request.
* @return string|false Class name for the first transport that claims to support the request.
* False if no transport claims to support the request.
*/
@@ -559,8 +559,8 @@ class WP_Http {
* @deprecated 5.1.0 Use WP_Http::request()
* @see WP_Http::request()
*
* @param string $url URL to Request.
* @param array $args Request arguments.
* @param string $url URL to request.
* @param array $args Request arguments.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
*/
@@ -615,7 +615,7 @@ class WP_Http {
*
* @since 2.7.0
*
* @param string $url The request URL.
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
@@ -633,7 +633,7 @@ class WP_Http {
*
* @since 2.7.0
*
* @param string $url The request URL.
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'.
* A WP_Error instance upon error.
@@ -675,7 +675,7 @@ class WP_Http {
* @since 2.7.0
*
* @param string|array $headers
* @param string $url The URL that was requested.
* @param string $url The URL that was requested.
* @return array Processed string headers. If duplicate headers are encountered,
* then a numbered array is returned as the value of that header-key.
*/
+3 -3
View File
@@ -118,8 +118,8 @@ class WP_Comment_Query {
*
* @since 4.0.0
*
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @return mixed|false Return value of the callback, false otherwise.
*/
public function __call( $name, $arguments ) {
@@ -1085,7 +1085,7 @@ class WP_Comment_Query {
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $string
* @param array $cols
* @param array $cols
* @return string
*/
protected function get_search_sql( $string, $cols ) {
@@ -6008,7 +6008,7 @@ final class WP_Customize_Manager {
* @since 4.7.0
*
* @param WP_Error $validity
* @param mixed $value
* @param mixed $value
* @return mixed
*/
public function _validate_header_video( $validity, $value ) {
@@ -6044,7 +6044,7 @@ final class WP_Customize_Manager {
* @since 4.7.0
*
* @param WP_Error $validity
* @param mixed $value
* @param mixed $value
* @return mixed
*/
public function _validate_external_header_video( $validity, $value ) {
+8 -8
View File
@@ -69,7 +69,7 @@ class WP_Date_Query {
* @since 4.0.0 The $inclusive logic was updated to include all times within the date range.
* @since 4.1.0 Introduced 'dayofweek_iso' time type parameter.
*
* @param array $date_query {
* @param array $date_query {
* Array of date query clauses.
*
* @type array ...$0 {
@@ -797,8 +797,8 @@ class WP_Date_Query {
*
* @since 3.7.0
*
* @param string $compare The compare operator to use
* @param string|array $value The value
* @param string $compare The compare operator to use.
* @param string|array $value The value.
* @return string|false|int The value to be used in SQL or false on error.
*/
public function build_value( $compare, $value ) {
@@ -956,11 +956,11 @@ class WP_Date_Query {
*
* @since 3.7.0
*
* @param string $column The column to query against. Needs to be pre-validated!
* @param string $compare The comparison operator. Needs to be pre-validated!
* @param int|null $hour Optional. An hour value (0-23).
* @param int|null $minute Optional. A minute value (0-59).
* @param int|null $second Optional. A second value (0-59).
* @param string $column The column to query against. Needs to be pre-validated!
* @param string $compare The comparison operator. Needs to be pre-validated!
* @param int|null $hour Optional. An hour value (0-23).
* @param int|null $minute Optional. A minute value (0-59).
* @param int|null $second Optional. A second value (0-59).
* @return string|false A query part or false on failure.
*/
public function build_time_query( $column, $compare, $hour = null, $minute = null, $second = null ) {
+2 -1
View File
@@ -1449,7 +1449,8 @@ final class _WP_Editors {
* @since 3.9.0
*
* @param string $mce_locale The locale used for the editor.
* @param bool $json_only optional Whether to include the JavaScript calls to tinymce.addI18n() and tinymce.ScriptLoader.markDone().
* @param bool $json_only Optional. Whether to include the JavaScript calls to tinymce.addI18n() and
* tinymce.ScriptLoader.markDone().
* @return string Translation object, JSON encoded.
*/
public static function wp_mce_translation( $mce_locale = '', $json_only = false ) {
+4 -4
View File
@@ -120,8 +120,8 @@ class WP_Embed {
*
* Do not use this function directly, use wp_embed_unregister_handler() instead.
*
* @param string $id The handler ID that should be removed.
* @param int $priority Optional. The priority of the handler to be removed (default: 10).
* @param string $id The handler ID that should be removed.
* @param int $priority Optional. The priority of the handler to be removed (default: 10).
*/
public function unregister_handler( $id, $priority = 10 ) {
unset( $this->handlers[ $priority ][ $id ] );
@@ -135,7 +135,7 @@ class WP_Embed {
*
* @since 5.5.0
*
* @param array $attr {
* @param array $attr {
* Shortcode attributes. Optional.
*
* @type int $width Width of the embed in pixels.
@@ -181,7 +181,7 @@ class WP_Embed {
* the registered embed handlers. If none of the regex matches and it's enabled, then the URL
* will be given to the WP_oEmbed class.
*
* @param array $attr {
* @param array $attr {
* Shortcode attributes. Optional.
*
* @type int $width Width of the embed in pixels.
+7 -7
View File
@@ -47,9 +47,9 @@ class WP_Error {
*
* @since 2.1.0
*
* @param string|int $code Error code
* @param string $message Error message
* @param mixed $data Optional. Error data.
* @param string|int $code Error code.
* @param string $message Error message.
* @param mixed $data Optional. Error data.
*/
public function __construct( $code = '', $message = '', $data = '' ) {
if ( empty( $code ) ) {
@@ -180,9 +180,9 @@ class WP_Error {
*
* @since 2.1.0
*
* @param string|int $code Error code.
* @param string $message Error message.
* @param mixed $data Optional. Error data.
* @param string|int $code Error code.
* @param string $message Error message.
* @param mixed $data Optional. Error data.
*/
public function add( $code, $message, $data = '' ) {
$this->errors[ $code ][] = $message;
@@ -198,7 +198,7 @@ class WP_Error {
*
* @since 2.1.0
*
* @param mixed $data Error data.
* @param mixed $data Error data.
* @param string|int $code Error code.
*/
public function add_data( $data, $code = '' ) {
+1 -1
View File
@@ -63,7 +63,7 @@ class WP_Http_Curl {
*
* @since 2.7.0
*
* @param string $url The request URL.
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
*/
+3 -3
View File
@@ -13,10 +13,10 @@ class WP_HTTP_IXR_Client extends IXR_Client {
public $error;
/**
* @param string $server
* @param string $server
* @param string|bool $path
* @param int|bool $port
* @param int $timeout
* @param int|bool $port
* @param int $timeout
*/
public function __construct( $server, $path = false, $port = false, $timeout = 15 ) {
if ( ! $path ) {
@@ -32,8 +32,8 @@ class WP_HTTP_Requests_Hooks extends Requests_Hooks {
/**
* Constructor.
*
* @param string $url URL to request.
* @param array $request Request data in WP_Http format.
* @param string $url URL to request.
* @param array $request Request data in WP_Http format.
*/
public function __construct( $url, $request ) {
$this->url = $url;
@@ -43,8 +43,8 @@ class WP_HTTP_Requests_Hooks extends Requests_Hooks {
/**
* Dispatch a Requests hook to a native WordPress action.
*
* @param string $hook Hook name.
* @param array $parameters Parameters to pass to callbacks.
* @param string $hook Hook name.
* @param array $parameters Parameters to pass to callbacks.
* @return boolean True if hooks were run, false if nothing was hooked.
*/
public function dispatch( $hook, $parameters = array() ) {
+1 -1
View File
@@ -22,7 +22,7 @@ class WP_Http_Streams {
* @since 2.7.0
* @since 3.7.0 Combined with the fsockopen transport and switched to stream_socket_client().
*
* @param string $url The request URL.
* @param string $url The request URL.
* @param string|array $args Optional. Override the defaults.
* @return array|WP_Error Array containing 'headers', 'body', 'response', 'cookies', 'filename'. A WP_Error instance upon error
*/
+5 -5
View File
@@ -171,8 +171,8 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
}
/**
* @param int $max_w
* @param int $max_h
* @param int $max_w
* @param int $max_h
* @param bool|array $crop
* @return resource|WP_Error
*/
@@ -415,7 +415,7 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
}
/**
* @param resource $image
* @param resource $image
* @param string|null $filename
* @param string|null $mime_type
* @return array|WP_Error
@@ -499,8 +499,8 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
* @since 3.5.0
*
* @param string|stream $filename
* @param callable $function
* @param array $arguments
* @param callable $function
* @param array $arguments
* @return bool
*/
protected function make_image( $filename, $function, $arguments ) {
@@ -662,8 +662,8 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor {
/**
* @param Imagick $image
* @param string $filename
* @param string $mime_type
* @param string $filename
* @param string $mime_type
* @return array|WP_Error
*/
protected function _save( $image, $filename = null, $mime_type = null ) {
+2 -2
View File
@@ -473,8 +473,8 @@ abstract class WP_Image_Editor {
* @since 3.5.0
*
* @param string|stream $filename
* @param callable $function
* @param array $arguments
* @param callable $function
* @param array $arguments
* @return bool
*/
protected function make_image( $filename, $function, $arguments ) {
+4 -4
View File
@@ -229,8 +229,8 @@ class WP_oEmbed {
*
* @since 4.0.0
*
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @return mixed|bool Return value of the callback, false otherwise.
*/
public function __call( $name, $arguments ) {
@@ -247,8 +247,8 @@ class WP_oEmbed {
*
* @see WP_oEmbed::discover()
*
* @param string $url The URL to the content.
* @param string|array $args Optional provider arguments.
* @param string $url The URL to the content.
* @param string|array $args Optional provider arguments.
* @return string|false The oEmbed provider URL on success, false on failure.
*/
public function get_provider( $url, $args = '' ) {
+2 -2
View File
@@ -3593,8 +3593,8 @@ class WP_Query {
*
* @since 4.0.0
*
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @return mixed|false Return value of the callback, false otherwise.
*/
public function __call( $name, $arguments ) {
+1 -1
View File
@@ -339,7 +339,7 @@ class WP_Recovery_Mode {
*
* @global array $wp_theme_directories
*
* @param array $error Error that was triggered.
* @param array $error Error that was triggered.
* @return array|false {
* @type string $slug The extension slug. This is the plugin or theme's directory.
* @type string $type The extension type. Either 'plugin' or 'theme'.
+6 -6
View File
@@ -95,8 +95,8 @@ class WP_Roles {
*
* @since 4.0.0
*
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @param string $name Method to call.
* @param array $arguments Arguments to pass when calling.
* @return mixed|false Return value of the callback, false otherwise.
*/
public function __call( $name, $arguments ) {
@@ -200,10 +200,10 @@ class WP_Roles {
*
* @since 2.0.0
*
* @param string $role Role name.
* @param string $cap Capability name.
* @param bool $grant Optional. Whether role is capable of performing capability.
* Default true.
* @param string $role Role name.
* @param string $cap Capability name.
* @param bool $grant Optional. Whether role is capable of performing capability.
* Default true.
*/
public function add_cap( $role, $cap, $grant = true ) {
if ( ! isset( $this->roles[ $role ] ) ) {
-1
View File
@@ -697,7 +697,6 @@ class WP_Term_Query {
* @param array|null $terms Return an array of term data to short-circuit WP's term query,
* or null to allow WP queries to run normally.
* @param WP_Term_Query $this The WP_Term_Query instance, passed by reference.
*
*/
$this->terms = apply_filters_ref_array( 'terms_pre_query', array( $this->terms, &$this ) );
@@ -100,7 +100,7 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
/**
* @ignore
*
* @param array $lines
* @param array $lines
* @param string $prefix
*/
public function _lines( $lines, $prefix = ' ' ) {
@@ -150,7 +150,7 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
* @ignore
*
* @param array $lines
* @param bool $encode
* @param bool $encode
* @return string
*/
public function _added( $lines, $encode = true ) {
@@ -188,7 +188,7 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
* @ignore
*
* @param array $lines
* @param bool $encode
* @param bool $encode
* @return string
*/
public function _deleted( $lines, $encode = true ) {
@@ -213,7 +213,7 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
* @ignore
*
* @param array $lines
* @param bool $encode
* @param bool $encode
* @return string
*/
public function _context( $lines, $encode = true ) {