From 0f1f17ebe2b3196d4ecab7cd04633af24567fde1 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 11 Aug 2022 14:01:35 +0000 Subject: [PATCH] Docs: Correct and improve the documented types for various functions and hooks. See #55646 git-svn-id: https://develop.svn.wordpress.org/trunk@53877 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/template.php | 4 ++-- src/wp-includes/blocks/search.php | 2 +- src/wp-includes/blocks/template-part.php | 4 ++-- src/wp-includes/class-wp-block-type.php | 22 +++++++++---------- src/wp-includes/class-wp-customize-panel.php | 4 ++-- src/wp-includes/link-template.php | 6 ++--- src/wp-includes/meta.php | 8 ++++++- src/wp-includes/post.php | 8 +++---- src/wp-includes/rest-api.php | 2 +- .../class-wp-rest-plugins-controller.php | 2 +- .../class-wp-rest-term-search-handler.php | 13 +++++++---- src/wp-includes/revision.php | 10 ++++----- src/wp-includes/taxonomy.php | 6 ++--- src/wp-includes/user.php | 14 ++++++------ 14 files changed, 58 insertions(+), 47 deletions(-) diff --git a/src/wp-admin/includes/template.php b/src/wp-admin/includes/template.php index 88f680c0cb..df886560f2 100644 --- a/src/wp-admin/includes/template.php +++ b/src/wp-admin/includes/template.php @@ -1776,7 +1776,7 @@ function do_settings_fields( $page, $section ) { * @since 3.0.0 * @since 5.3.0 Added `warning` and `info` as possible values for `$type`. * - * @global array $wp_settings_errors Storage array of errors registered during this pageload + * @global array[] $wp_settings_errors Storage array of errors registered during this pageload * * @param string $setting Slug title of the setting to which this error applies. * @param string $code Slug-name to identify the error. Used as part of 'id' attribute in HTML output. @@ -1813,7 +1813,7 @@ function add_settings_error( $setting, $code, $message, $type = 'error' ) { * * @since 3.0.0 * - * @global array $wp_settings_errors Storage array of errors registered during this pageload + * @global array[] $wp_settings_errors Storage array of errors registered during this pageload * * @param string $setting Optional. Slug title of a specific setting whose errors you want. * @param bool $sanitize Optional. Whether to re-sanitize the setting value before returning errors. diff --git a/src/wp-includes/blocks/search.php b/src/wp-includes/blocks/search.php index 94ec6fc4ac..280360b86e 100644 --- a/src/wp-includes/blocks/search.php +++ b/src/wp-includes/blocks/search.php @@ -180,7 +180,7 @@ function classnames_for_block_core_search( $attributes ) { * * @param array $attributes The block attributes. * - * @return array Style HTML attribute. + * @return string[] Style HTML attributes. */ function styles_for_block_core_search( $attributes ) { $wrapper_styles = array(); diff --git a/src/wp-includes/blocks/template-part.php b/src/wp-includes/blocks/template-part.php index d1343249ed..94be0b53b1 100644 --- a/src/wp-includes/blocks/template-part.php +++ b/src/wp-includes/blocks/template-part.php @@ -159,9 +159,9 @@ function render_block_core_template_part( $attributes ) { } /** - * Returns an array of variation objects for the template part block. + * Returns an array of variation arrays for the template part block. * - * @return array Array containing the block variation objects. + * @return array[] Array containing the block variation data in an array. */ function build_template_part_block_variations() { $variations = array(); diff --git a/src/wp-includes/class-wp-block-type.php b/src/wp-includes/class-wp-block-type.php index 6902b36773..1c01120f87 100644 --- a/src/wp-includes/class-wp-block-type.php +++ b/src/wp-includes/class-wp-block-type.php @@ -54,7 +54,7 @@ class WP_Block_Type { * when nested within the specified blocks. * * @since 5.5.0 - * @var array|null + * @var string[]|null */ public $parent = null; @@ -63,7 +63,7 @@ class WP_Block_Type { * block types at any position of the ancestor's block subtree. * * @since 6.0.0 - * @var array|null + * @var string[]|null */ public $ancestor = null; @@ -112,7 +112,7 @@ class WP_Block_Type { * Block variations. * * @since 5.8.0 - * @var array + * @var array[] */ public $variations = array(); @@ -152,7 +152,7 @@ class WP_Block_Type { * Context values inherited by blocks of this type. * * @since 5.5.0 - * @var array + * @var string[] */ public $uses_context = array(); @@ -160,7 +160,7 @@ class WP_Block_Type { * Context provided by blocks of this type. * * @since 5.5.0 - * @var array|null + * @var string[]|null */ public $provides_context = null; @@ -239,23 +239,23 @@ class WP_Block_Type { * @type string $title Human-readable block type label. * @type string|null $category Block type category classification, used in * search interfaces to arrange block types by category. - * @type array|null $parent Setting parent lets a block require that it is only + * @type string[]|null $parent Setting parent lets a block require that it is only * available when nested within the specified blocks. - * @type array|null $ancestor Setting ancestor makes a block available only inside the specified + * @type string[]|null $ancestor Setting ancestor makes a block available only inside the specified * block types at any position of the ancestor's block subtree. * @type string|null $icon Block type icon. * @type string $description A detailed block type description. * @type string[] $keywords Additional keywords to produce block type as * result in search interfaces. * @type string|null $textdomain The translation textdomain. - * @type array $styles Alternative block styles. - * @type array $variations Block variations. + * @type array[] $styles Alternative block styles. + * @type array[] $variations Block variations. * @type array|null $supports Supported features. * @type array|null $example Structured data for the block preview. * @type callable|null $render_callback Block type render callback. * @type array|null $attributes Block type attributes property schemas. - * @type array $uses_context Context values inherited by blocks of this type. - * @type array|null $provides_context Context provided by blocks of this type. + * @type string[] $uses_context Context values inherited by blocks of this type. + * @type string[]|null $provides_context Context provided by blocks of this type. * @type string|null $editor_script Block type editor only script handle. * @type string|null $script Block type front end and editor script handle. * @type string|null $view_script Block type front end only script handle. diff --git a/src/wp-includes/class-wp-customize-panel.php b/src/wp-includes/class-wp-customize-panel.php index 6ec6cd55e0..88d72f83fc 100644 --- a/src/wp-includes/class-wp-customize-panel.php +++ b/src/wp-includes/class-wp-customize-panel.php @@ -72,7 +72,7 @@ class WP_Customize_Panel { * Theme features required to support the panel. * * @since 4.0.0 - * @var string|string[] + * @var mixed[] */ public $theme_supports = ''; @@ -146,7 +146,7 @@ class WP_Customize_Panel { * of panels and sections. Default 160. * @type string $capability Capability required for the panel. * Default `edit_theme_options`. - * @type string|string[] $theme_supports Theme features required to support the panel. + * @type mixed[] $theme_supports Theme features required to support the panel. * @type string $title Title of the panel to show in UI. * @type string $description Description to show in the UI. * @type string $type Type of the panel. diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php index e150d301fc..7dcda3f9e6 100644 --- a/src/wp-includes/link-template.php +++ b/src/wp-includes/link-template.php @@ -4239,9 +4239,9 @@ function is_avatar_comment_type( $comment_type ) { * @return array { * Along with the arguments passed in `$args`, this will contain a couple of extra arguments. * - * @type bool $found_avatar True if we were able to find an avatar for this user, - * false or not set if we couldn't. - * @type string $url The URL of the avatar we found. + * @type bool $found_avatar True if an avatar was found for this user, + * false or not set if none was found. + * @type string|false $url The URL of the avatar that was found, or false. * } */ function get_avatar_data( $id_or_email, $args = null ) { diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php index 420e0f1f9b..5a0f9d96c7 100644 --- a/src/wp-includes/meta.php +++ b/src/wp-includes/meta.php @@ -1231,7 +1231,13 @@ function wp_metadata_lazyloader() { * @param string $primary_table Primary database table name. * @param string $primary_id_column Primary ID column name. * @param object $context Optional. The main query object - * @return array Associative array of `JOIN` and `WHERE` SQL. + * @return string[]|false { + * Array containing JOIN and WHERE SQL clauses to append to the main query, + * or false if no table exists for the requested meta type. + * + * @type string $join SQL fragment to append to the main JOIN clause. + * @type string $where SQL fragment to append to the main WHERE clause. + * } */ function get_meta_sql( $meta_query, $type, $primary_table, $primary_id_column, $context = null ) { $meta_query_obj = new WP_Meta_Query( $meta_query ); diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 48122ffbfb..d53508f19b 100644 --- a/src/wp-includes/post.php +++ b/src/wp-includes/post.php @@ -861,7 +861,7 @@ function _wp_relative_upload_path( $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. - * @return WP_Post[]|int[] Array of post objects or post IDs. + * @return WP_Post[]|array[]|int[] Array of post objects, arrays, or IDs, depending on `$output`. */ function get_children( $args = '', $output = OBJECT ) { $kids = array(); @@ -5806,9 +5806,9 @@ function get_page_by_title( $page_title, $output = OBJECT, $post_type = 'page' ) * * @since 1.5.1 * - * @param int $page_id Page ID. - * @param array $pages List of page objects from which descendants should be identified. - * @return array List of page children. + * @param int $page_id Page ID. + * @param WP_Post[] $pages List of page objects from which descendants should be identified. + * @return WP_Post[] List of page children. */ function get_page_children( $page_id, $pages ) { // Build a hash of ID -> children. diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php index 81156911c3..01a1a9a50c 100644 --- a/src/wp-includes/rest-api.php +++ b/src/wp-includes/rest-api.php @@ -1191,7 +1191,7 @@ function rest_add_application_passwords_to_index( $response ) { * * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. - * @return array Avatar URLs keyed by size. Each value can be a URL string or boolean false. + * @return (string|false)[] Avatar URLs keyed by size. Each value can be a URL string or boolean false. */ function rest_get_avatar_urls( $id_or_email ) { $avatar_sizes = rest_get_avatar_sizes(); diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php index a31f11396f..9e9441085a 100644 --- a/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php +++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-plugins-controller.php @@ -571,7 +571,7 @@ class WP_REST_Plugins_Controller extends WP_REST_Controller { * * @since 5.5.0 * - * @param mixed $item Unmarked up and untranslated plugin data from {@see get_plugin_data()}. + * @param array $item Unmarked up and untranslated plugin data from {@see get_plugin_data()}. * @param WP_REST_Request $request Request object. * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure. */ diff --git a/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php b/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php index 90abe743c6..af9b2e5663 100644 --- a/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php +++ b/src/wp-includes/rest-api/search/class-wp-rest-term-search-handler.php @@ -41,9 +41,14 @@ class WP_REST_Term_Search_Handler extends WP_REST_Search_Handler { * @since 5.6.0 * * @param WP_REST_Request $request Full REST request. - * @return array Associative array containing an `WP_REST_Search_Handler::RESULT_IDS` containing - * an array of found IDs and `WP_REST_Search_Handler::RESULT_TOTAL` containing the - * total count for the matching search results. + * @return array { + * Associative array containing found IDs and total count for the matching search results. + * + * @type int[] $ids Found IDs. + * @type string|int|WP_Error $total Numeric string containing the number of terms in that + * taxonomy, 0 if there are no results, or WP_Error if + * the requested taxonomy does not exist. + * } */ public function search_items( WP_REST_Request $request ) { $taxonomies = $request[ WP_REST_Search_Controller::PROP_SUBTYPE ]; @@ -132,7 +137,7 @@ class WP_REST_Term_Search_Handler extends WP_REST_Search_Handler { * @since 5.6.0 * * @param int $id Item ID. - * @return array Links for the given item. + * @return array[] Array of link arrays for the given item. */ public function prepare_item_links( $id ) { $term = get_term( $id ); diff --git a/src/wp-includes/revision.php b/src/wp-includes/revision.php index 584baf2336..be3f62cbc2 100644 --- a/src/wp-includes/revision.php +++ b/src/wp-includes/revision.php @@ -17,7 +17,7 @@ * @param array|WP_Post $post Optional. A post array or a WP_Post object being processed * for insertion as a post revision. Default empty array. * @param bool $deprecated Not used. - * @return array Array of fields that can be versioned. + * @return string[] Array of fields that can be versioned. */ function _wp_post_revision_fields( $post = array(), $deprecated = false ) { static $fields = null; @@ -47,9 +47,9 @@ function _wp_post_revision_fields( $post = array(), $deprecated = false ) { * @since 2.6.0 * @since 4.5.0 The `$post` parameter was added. * - * @param array $fields List of fields to revision. Contains 'post_title', - * 'post_content', and 'post_excerpt' by default. - * @param array $post A post array being processed for insertion as a post revision. + * @param string[] $fields List of fields to revision. Contains 'post_title', + * 'post_content', and 'post_excerpt' by default. + * @param array $post A post array being processed for insertion as a post revision. */ $fields = apply_filters( '_wp_post_revision_fields', $fields, $post ); @@ -489,7 +489,7 @@ function wp_delete_post_revision( $revision ) { * * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`. * @param array|null $args Optional. Arguments for retrieving post revisions. Default null. - * @return array An array of revisions, or an empty array if none. + * @return WP_Post[]|int[] Array of revision objects or IDs, or an empty array if none. */ function wp_get_post_revisions( $post = 0, $args = null ) { $post = get_post( $post ); diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index 687ac3bb8c..f731e4f46a 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -1856,8 +1856,8 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) { * * @internal The `$deprecated` parameter is parsed for backward compatibility only. * - * @param array|string $args Optional. Array of arguments that get passed to get_terms(). - * Default empty array. + * @param array|string $args Optional. Array or string of arguments. See WP_Term_Query::__construct() + * for information on accepted arguments. Default empty array. * @param array|string $deprecated Optional. Argument array, when using the legacy function parameter format. * If present, this parameter will be interpreted as `$args`, and the first * function parameter will be parsed as a taxonomy or array of taxonomies. @@ -4700,7 +4700,7 @@ function the_taxonomies( $args = array() ) { * @type string $term_template Template for displaying a single term in the list. Default is the term name * linked to its archive. * } - * @return array List of taxonomies. + * @return string[] List of taxonomies. */ function get_the_taxonomies( $post = 0, $args = array() ) { $post = get_post( $post ); diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php index 416db2b86f..976083a246 100644 --- a/src/wp-includes/user.php +++ b/src/wp-includes/user.php @@ -1213,10 +1213,10 @@ function count_users( $strategy = 'time', $site_id = null ) { * * @since 5.1.0 * - * @param null|string $result The value to return instead. Default null to continue with the query. - * @param string $strategy Optional. The computational strategy to use when counting the users. - * Accepts either 'time' or 'memory'. Default 'time'. - * @param int|null $site_id Optional. The site ID to count users for. Defaults to the current site. + * @param null|array $result The value to return instead. Default null to continue with the query. + * @param string $strategy Optional. The computational strategy to use when counting the users. + * Accepts either 'time' or 'memory'. Default 'time'. + * @param int $site_id The site ID to count users for. */ $pre = apply_filters( 'pre_count_users', null, $strategy, $site_id ); @@ -3743,7 +3743,7 @@ function new_user_email_admin_notice() { * @since 4.9.6 * @access private * - * @return array List of core privacy action types. + * @return string[] List of core privacy action types. */ function _wp_privacy_action_request_types() { return array( @@ -3757,8 +3757,8 @@ function _wp_privacy_action_request_types() { * * @since 4.9.6 * - * @param array $exporters An array of personal data exporters. - * @return array An array of personal data exporters. + * @param array[] $exporters An array of personal data exporters. + * @return array[] An array of personal data exporters. */ function wp_register_user_personal_data_exporter( $exporters ) { $exporters['wordpress-user'] = array(