Docs: Miscellaneous DocBlock corrections.

See #49572.

git-svn-id: https://develop.svn.wordpress.org/trunk@48591 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2020-07-23 21:53:43 +00:00
parent 81a12a7bec
commit b932c543a2
10 changed files with 76 additions and 63 deletions

View File

@ -14,9 +14,9 @@
* @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 $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.
*/

View File

@ -80,9 +80,9 @@ 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,
* @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'.
* @return object|array|WP_Error|null Category data in type defined by $output parameter.
@ -116,8 +116,8 @@ function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
*
* @param string $category_path URL containing category slugs.
* @param bool $full_match Optional. Whether full path should be matched.
* @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,
* @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.
* @return WP_Term|array|WP_Error|null Type is based on $output value.
*/
@ -329,8 +329,8 @@ function get_tags( $args = '' ) {
* @since 2.3.0
*
* @param int|WP_Term|object $tag A tag ID or 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,
* @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 tag fields. Default 'raw'.
* @return WP_Term|array|WP_Error|null Tag data in type defined by $output parameter.
@ -371,7 +371,7 @@ function clean_category_cache( $id ) {
* @since 4.4.0 The `$category` parameter now also accepts a WP_Term object.
* @access private
*
* @param array|object|WP_Term $category Category Row object or array
* @param array|object|WP_Term $category Category row object or array.
*/
function _make_cat_compat( &$category ) {
if ( is_object( $category ) && ! is_wp_error( $category ) ) {

View File

@ -56,8 +56,8 @@ class WP_User {
* Capabilities that the individual user has been granted outside of those inherited from their role.
*
* @since 2.0.0
* @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
* @var bool[] Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
*/
public $caps = array();
@ -81,8 +81,8 @@ class WP_User {
* All capabilities the user has, including individual and role based.
*
* @since 2.0.0
* @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
* @var bool[] Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
*/
public $allcaps = array();
@ -482,15 +482,17 @@ class WP_User {
}
/**
* Retrieves all of the capabilities of the roles of the user, and merges them with individual user capabilities.
* Retrieves all of the capabilities of the user's roles, and merges them with
* individual user capabilities.
*
* All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means
* that the user can be denied specific capabilities that their role might have, but the user is specifically denied.
* All of the capabilities of the user's roles are merged with the user's individual
* capabilities. This means that the user can be denied specific capabilities that
* their role might have, but the user is specifically denied.
*
* @since 2.0.0
*
* @return bool[] Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
* @return bool[] Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
*/
public function get_role_caps() {
$switch_site = false;
@ -766,8 +768,8 @@ class WP_User {
* @since 2.0.0
* @since 3.7.0 Added the `$user` parameter.
*
* @param bool[] $allcaps Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
* @param bool[] $allcaps Array of key/value pairs where keys represent a capability name
* and boolean values represent whether the user has that capability.
* @param string[] $caps Required primitive capabilities for the requested capability.
* @param array $args {
* Arguments that accompany the requested capability check.

View File

@ -187,8 +187,9 @@ function get_approved_comments( $post_id, $args = array() ) {
* @global WP_Comment $comment Global comment object.
*
* @param WP_Comment|string|int $comment Comment to retrieve.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Comment object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Comment object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @return WP_Comment|array|null Depends on $output value.
*/
function get_comment( &$comment = null, $output = OBJECT ) {

View File

@ -7524,10 +7524,10 @@ function get_dirsize( $directory, $max_execution_time = null ) {
* @since 5.2.0 $max_execution_time parameter added.
*
* @param string $directory Full path of a directory.
* @param string|array $exclude Optional. Full path of a subdirectory to exclude from the total, or array of
* paths. Expected without trailing slash(es).
* @param int $max_execution_time Maximum time to run before giving up. In seconds.
* The timeout is global and is measured from the moment WordPress started to load.
* @param string|array $exclude Optional. Full path of a subdirectory to exclude from the total,
* or array of paths. Expected without trailing slash(es).
* @param int $max_execution_time Maximum time to run before giving up. In seconds. The timeout is global
* and is measured from the moment WordPress started to load.
* @return int|false|null Size in bytes if a valid directory. False if not. Null if timeout.
*/
function recurse_dirsize( $directory, $exclude = null, $max_execution_time = null ) {

View File

@ -484,7 +484,8 @@ function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $
* or an array of values if it's false.
*
* If the meta field does not exist, the result depends on get_metadata_default().
* By default, an empty string is returned if `$single` is true, or an empty array if it's false.
* By default, an empty string is returned if `$single` is true, or an empty array
* if it's false.
*
* @since 2.9.0
*
@ -591,7 +592,8 @@ function get_metadata_raw( $meta_type, $object_id, $meta_key = '', $single = fal
/**
* Retrieves default metadata value for the specified object.
*
* By default, an empty string is returned if `$single` is true, or an empty array if it's false.
* By default, an empty string is returned if `$single` is true, or an empty array
* if it's false.
*
* @since 5.5.0
*
@ -1413,7 +1415,7 @@ function filter_default_metadata( $value, $object_id, $meta_key, $single, $meta_
return $value;
}
// If this meta type does not have sub types, then the default is keyed as an empty string.
// If this meta type does not have subtypes, then the default is keyed as an empty string.
if ( isset( $defaults[''] ) ) {
$metadata = $defaults[''];
} else {

View File

@ -633,8 +633,9 @@ function _wp_relative_upload_path( $path ) {
* @global WP_Post $post Global post object.
*
* @param mixed $args Optional. User defined arguments for replacing the defaults. Default empty.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Post object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @return WP_Post[]|int[] Array of post objects or post IDs.
*/
function get_children( $args = '', $output = OBJECT ) {
@ -751,8 +752,9 @@ function get_extended( $post ) {
* @global WP_Post $post Global post object.
*
* @param int|WP_Post|null $post Optional. Post ID or post object. Defaults to global $post.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Post object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. Type of filter to apply. Accepts 'raw', 'edit', 'db',
* or 'display'. Default 'raw'.
* @return WP_Post|array|null Type corresponding to $output on success or null on failure.
@ -3505,10 +3507,11 @@ function wp_get_post_terms( $post_id = 0, $taxonomy = 'post_tag', $args = array(
* @see get_posts()
*
* @param array $args Optional. Arguments to retrieve posts. Default empty array.
* @param string $output Optional. The required return type. One of OBJECT or ARRAY_A, which correspond to
* a WP_Post object or an associative array, respectively. Default ARRAY_A.
* @return array|false Array of recent posts, where the type of each element is determined by $output parameter.
* Empty array on failure.
* @param string $output Optional. The required return type. One of OBJECT or ARRAY_A, which
* correspond to a WP_Post object or an associative array, respectively.
* Default ARRAY_A.
* @return array|false Array of recent posts, where the type of each element is determined
* by the `$output` parameter. Empty array on failure.
*/
function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) {
@ -5048,8 +5051,9 @@ function get_all_page_ids() {
* @deprecated 3.5.0 Use get_post()
*
* @param int|WP_Post $page Page object or page ID. Passed by reference.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Post object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. How the return value should be filtered. Accepts 'raw',
* 'edit', 'db', 'display'. Default 'raw'.
* @return WP_Post|array|null WP_Post or array on success, null on failure.
@ -5066,8 +5070,9 @@ function get_page( $page, $output = OBJECT, $filter = 'raw' ) {
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $page_path Page path.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Post object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string|array $post_type Optional. Post type or array of post types. Default 'page'.
* @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
*/
@ -5168,8 +5173,9 @@ function get_page_by_path( $page_path, $output = OBJECT, $post_type = 'page' ) {
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $page_title Page title.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Post object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string|array $post_type Optional. Post type or array of post types. Default 'page'.
* @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
*/

View File

@ -354,8 +354,9 @@ function _wp_put_post_revision( $post = null, $autosave = false ) {
* @since 2.6.0
*
* @param int|WP_Post $post The post ID or object.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
* a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond to a WP_Post object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional sanitation filter. See sanitize_post().
* @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
*/

View File

@ -839,18 +839,18 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
*
* @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
*
* @param int|WP_Term|object $term If integer, term data will be fetched from the database, or from the cache if
* available. If stdClass object (as in the results of a database query), will apply
* filters and return a `WP_Term` object corresponding to the `$term` data. If
* `WP_Term`, will return `$term`.
* @param string $taxonomy Optional. Taxonomy name that $term is part of.
* @param int|WP_Term|object $term If integer, term data will be fetched from the database,
* or from the cache if available.
* If stdClass object (as in the results of a database query),
* will apply filters and return a `WP_Term` object with the `$term` data.
* If `WP_Term`, will return `$term`.
* @param string $taxonomy Optional. Taxonomy name that `$term` is part of.
* @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which
* correspond toa WP_Term object, an associative array, or a numeric array
* correspond to a WP_Term object, an associative array, or a numeric array,
* respectively. Default OBJECT.
* @param string $filter Optional. How to sanitize term fields. Default 'raw'.
* @return WP_Term|array|WP_Error|null Object of the type specified by `$output` on success. When `$output` is 'OBJECT',
* a WP_Term instance is returned. If taxonomy does not exist, a WP_Error is
* returned. Returns null for miscellaneous failure.
* @return WP_Term|array|WP_Error|null WP_Term instance (or array) on success, depending on the `$output` value.
* WP_Error if `$taxonomy` does not exist. Null for miscellaneous failure.
*/
function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
if ( empty( $term ) ) {
@ -956,11 +956,12 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
* @param string $field Either 'slug', 'name', 'id' or 'ID' (term_id), or 'term_taxonomy_id'.
* @param string|int $value Search for this term value.
* @param string $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
* @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 $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 term fields. Default 'raw'.
* @return WP_Term|array|false WP_Term instance (or array) on success. Will return false if `$taxonomy` does not exist
* or `$term` was not found.
* @return WP_Term|array|false WP_Term instance (or array) on success, depending on the `$output` value.
* False if `$taxonomy` does not exist or `$term` was not found.
*/
function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {

View File

@ -2576,9 +2576,9 @@ class wpdb {
* @since 0.71
*
* @param string|null $query SQL query.
* @param string $output Optional. The required return type. Possible values include
* OBJECT, ARRAY_A, or ARRAY_N, which correspond to an stdClass object,
* an associative array, or a numeric array, respectively. Default OBJECT.
* @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 int $y Optional. Row to return. Indexed from 0.
* @return array|object|null|void Database query result in format specified by $output or null on failure.
*/