From cc24b047eb57f338fab03e162a555e5e989f458c Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 27 Apr 2023 22:29:18 +0000 Subject: [PATCH] Docs: Correct and improve various documented types for properties, functions, and hooks. See #57840 Built from https://develop.svn.wordpress.org/trunk@55693 git-svn-id: http://core.svn.wordpress.org/trunk@55205 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/class-wp-screen.php | 4 +- wp-includes/block-template-utils.php | 45 +++++++------- .../class-wp-block-patterns-registry.php | 58 +++++++++---------- wp-includes/class-wp-block-template.php | 8 +-- wp-includes/http.php | 2 +- wp-includes/link-template.php | 4 +- wp-includes/rest-api/class-wp-rest-server.php | 4 +- wp-includes/taxonomy.php | 6 +- wp-includes/version.php | 2 +- 9 files changed, 70 insertions(+), 63 deletions(-) diff --git a/wp-admin/includes/class-wp-screen.php b/wp-admin/includes/class-wp-screen.php index 1d3e8d7fe2..d04d9a75b2 100644 --- a/wp-admin/includes/class-wp-screen.php +++ b/wp-admin/includes/class-wp-screen.php @@ -89,7 +89,7 @@ final class WP_Screen { * have a `$parent_base` of 'edit'. * * @since 3.3.0 - * @var string + * @var string|null */ public $parent_base; @@ -99,7 +99,7 @@ final class WP_Screen { * Some `$parent_file` values are 'edit.php?post_type=page', 'edit.php', and 'options-general.php'. * * @since 3.3.0 - * @var string + * @var string|null */ public $parent_file; diff --git a/wp-includes/block-template-utils.php b/wp-includes/block-template-utils.php index 1e9c0a5676..83457ecd00 100644 --- a/wp-includes/block-template-utils.php +++ b/wp-includes/block-template-utils.php @@ -59,7 +59,7 @@ function get_block_theme_folders( $theme_stylesheet = null ) { * * @since 5.9.0 * - * @return array The supported template part area values. + * @return array[] The supported template part area values. */ function get_allowed_block_template_part_areas() { $default_area_definitions = array( @@ -97,7 +97,7 @@ function get_allowed_block_template_part_areas() { * * @since 5.9.0 * - * @param array $default_area_definitions An array of supported area objects. + * @param array[] $default_area_definitions An array of supported area objects. */ return apply_filters( 'default_wp_template_part_areas', $default_area_definitions ); } @@ -109,7 +109,7 @@ function get_allowed_block_template_part_areas() { * * @since 5.9.0 * - * @return array The default template types. + * @return array[] The default template types. */ function get_default_block_template_types() { $default_template_types = array( @@ -184,7 +184,7 @@ function get_default_block_template_types() { * * @since 5.9.0 * - * @param array $default_template_types An array of template types, formatted as [ slug => [ title, description ] ]. + * @param array[] $default_template_types An array of template types, formatted as [ slug => [ title, description ] ]. */ return apply_filters( 'default_template_types', $default_template_types ); } @@ -227,7 +227,7 @@ function _filter_block_template_part_area( $type ) { * @access private * * @param string $base_directory The theme's file path. - * @return array A list of paths to all template part files. + * @return string[] A list of paths to all template part files. */ function _get_block_templates_paths( $base_directory ) { $path_list = array(); @@ -926,13 +926,13 @@ function _build_block_template_result_from_post( $post ) { * @param array $query { * Optional. Arguments to retrieve templates. * - * @type array $slug__in List of slugs to include. - * @type int $wp_id Post ID of customized template. - * @type string $area A 'wp_template_part_area' taxonomy value to filter by (for wp_template_part template type only). - * @type string $post_type Post type to get the templates for. + * @type string[] $slug__in List of slugs to include. + * @type int $wp_id Post ID of customized template. + * @type string $area A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only). + * @type string $post_type Post type to get the templates for. * } * @param string $template_type 'wp_template' or 'wp_template_part'. - * @return array Templates. + * @return WP_Block_Template[] Array of block templates. */ function get_block_templates( $query = array(), $template_type = 'wp_template' ) { /** @@ -943,15 +943,16 @@ function get_block_templates( $query = array(), $template_type = 'wp_template' ) * @since 5.9.0 * * @param WP_Block_Template[]|null $block_templates Return an array of block templates to short-circuit the default query, - * or null to allow WP to run it's normal queries. + * or null to allow WP to run its normal queries. * @param array $query { - * Optional. Arguments to retrieve templates. + * Arguments to retrieve templates. All arguments are optional. * - * @type array $slug__in List of slugs to include. - * @type int $wp_id Post ID of customized template. - * @type string $post_type Post type to get the templates for. + * @type string[] $slug__in List of slugs to include. + * @type int $wp_id Post ID of customized template. + * @type string $area A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only). + * @type string $post_type Post type to get the templates for. * } - * @param string $template_type wp_template or wp_template_part. + * @param string $template_type 'wp_template' or 'wp_template_part'. */ $templates = apply_filters( 'pre_get_block_templates', null, $query, $template_type ); if ( ! is_null( $templates ) ) { @@ -1036,13 +1037,15 @@ function get_block_templates( $query = array(), $template_type = 'wp_template' ) * @since 5.9.0 * * @param WP_Block_Template[] $query_result Array of found block templates. - * @param array $query { - * Optional. Arguments to retrieve templates. + * @param array $query { + * Arguments to retrieve templates. All arguments are optional. * - * @type array $slug__in List of slugs to include. - * @type int $wp_id Post ID of customized template. + * @type string[] $slug__in List of slugs to include. + * @type int $wp_id Post ID of customized template. + * @type string $area A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only). + * @type string $post_type Post type to get the templates for. * } - * @param string $template_type wp_template or wp_template_part. + * @param string $template_type wp_template or wp_template_part. */ return apply_filters( 'get_block_templates', $query_result, $query, $template_type ); } diff --git a/wp-includes/class-wp-block-patterns-registry.php b/wp-includes/class-wp-block-patterns-registry.php index cea626eb12..a83b35185b 100644 --- a/wp-includes/class-wp-block-patterns-registry.php +++ b/wp-includes/class-wp-block-patterns-registry.php @@ -50,35 +50,35 @@ final class WP_Block_Patterns_Registry { * @param array $pattern_properties { * List of properties for the block pattern. * - * @type string $title Required. A human-readable title for the pattern. - * @type string $content Required. Block HTML markup for the pattern. - * @type string $description Optional. Visually hidden text used to describe the pattern - * in the inserter. A description is optional, but is strongly - * encouraged when the title does not fully describe what the - * pattern does. The description will help users discover the - * pattern while searching. - * @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled - * preview within the pattern inserter. - * @type bool $inserter Optional. Determines whether the pattern is visible in inserter. - * To hide a pattern so that it can only be inserted programmatically, - * set this to false. Default true. - * @type array $categories Optional. A list of registered pattern categories used to group - * block patterns. Block patterns can be shown on multiple categories. - * A category must be registered separately in order to be used here. - * @type array $keywords Optional. A list of aliases or keywords that help users discover - * the pattern while searching. - * @type array $blockTypes Optional. A list of block names including namespace that could use - * the block pattern in certain contexts (placeholder, transforms). - * The block pattern is available in the block editor inserter - * regardless of this list of block names. - * Certain blocks support further specificity besides the block name - * (e.g. for `core/template-part` you can specify areas - * like `core/template-part/header` or `core/template-part/footer`). - * @type array $postTypes Optional. An array of post types that the pattern is restricted - * to be used with. The pattern will only be available when editing one - * of the post types passed on the array. For all the other post types - * not part of the array the pattern is not available at all. - * @type array $templateTypes Optional. An array of template types where the pattern fits. + * @type string $title Required. A human-readable title for the pattern. + * @type string $content Required. Block HTML markup for the pattern. + * @type string $description Optional. Visually hidden text used to describe the pattern + * in the inserter. A description is optional, but is strongly + * encouraged when the title does not fully describe what the + * pattern does. The description will help users discover the + * pattern while searching. + * @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled + * preview within the pattern inserter. + * @type bool $inserter Optional. Determines whether the pattern is visible in inserter. + * To hide a pattern so that it can only be inserted programmatically, + * set this to false. Default true. + * @type string[] $categories Optional. A list of registered pattern categories used to group + * block patterns. Block patterns can be shown on multiple categories. + * A category must be registered separately in order to be used here. + * @type string[] $keywords Optional. A list of aliases or keywords that help users discover + * the pattern while searching. + * @type string[] $blockTypes Optional. A list of block names including namespace that could use + * the block pattern in certain contexts (placeholder, transforms). + * The block pattern is available in the block editor inserter + * regardless of this list of block names. + * Certain blocks support further specificity besides the block name + * (e.g. for `core/template-part` you can specify areas + * like `core/template-part/header` or `core/template-part/footer`). + * @type string[] $postTypes Optional. An array of post types that the pattern is restricted + * to be used with. The pattern will only be available when editing one + * of the post types passed on the array. For all the other post types + * not part of the array the pattern is not available at all. + * @type string[] $templateTypes Optional. An array of template types where the pattern fits. * } * @return bool True if the pattern was registered with success and false otherwise. */ diff --git a/wp-includes/class-wp-block-template.php b/wp-includes/class-wp-block-template.php index 898ddf0dd3..75bfd4747d 100644 --- a/wp-includes/class-wp-block-template.php +++ b/wp-includes/class-wp-block-template.php @@ -84,7 +84,7 @@ class WP_Block_Template { * 'custom'. * * @since 5.9.0 - * @var string + * @var string|null */ public $origin; @@ -127,7 +127,7 @@ class WP_Block_Template { * A value of 0 means no author. * * @since 5.9.0 - * @var int + * @var int|null */ public $author; @@ -135,7 +135,7 @@ class WP_Block_Template { * Post types. * * @since 5.9.0 - * @var array + * @var string[]|null */ public $post_types; @@ -143,7 +143,7 @@ class WP_Block_Template { * Area. * * @since 5.9.0 - * @var string + * @var string|null */ public $area; } diff --git a/wp-includes/http.php b/wp-includes/http.php index b48c3b1cb7..85107ef4b6 100644 --- a/wp-includes/http.php +++ b/wp-includes/http.php @@ -593,7 +593,7 @@ function wp_http_validate_url( $url ) { * * @since 5.9.0 * - * @param array $allowed_ports Array of integers for valid ports. + * @param int[] $allowed_ports Array of integers for valid ports. * @param string $host Host name of the requested URL. * @param string $url Requested URL. */ diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index e43b074657..c5951c15ba 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -4722,7 +4722,7 @@ function get_the_privacy_policy_link( $before = '', $after = '' ) { /** * Returns an array of URL hosts which are considered to be internal hosts. * - * By default the list of internal hosts is comproside of the PHP_URL_HOST of + * By default the list of internal hosts is comprised of the host name of * the site's home_url() (as parsed by wp_parse_url()). * * This list is used when determining if a specificed URL is a link to a page on @@ -4745,7 +4745,7 @@ function wp_internal_hosts() { * * @since 6.2.0 * - * @param array $internal_hosts An array of internal URL hostnames. + * @param string[] $internal_hosts An array of internal URL hostnames. */ $internal_hosts = apply_filters( 'wp_internal_hosts', diff --git a/wp-includes/rest-api/class-wp-rest-server.php b/wp-includes/rest-api/class-wp-rest-server.php index 4c017eeefa..40666f82e5 100644 --- a/wp-includes/rest-api/class-wp-rest-server.php +++ b/wp-includes/rest-api/class-wp-rest-server.php @@ -158,8 +158,8 @@ class WP_REST_Server { * * @since 4.4.0 * - * @return WP_Error|null WP_Error indicates unsuccessful login, null indicates successful - * or no authentication provided + * @return WP_Error|null|true WP_Error indicates unsuccessful login, null indicates successful + * or no authentication provided */ public function check_authentication() { /** diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 925bcb41ee..e0659af2b0 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -814,7 +814,11 @@ function unregister_taxonomy_for_object_type( $taxonomy, $object_type ) { * * @param int|int[] $term_ids Term ID or array of term IDs of terms that will be used. * @param string|string[] $taxonomies String of taxonomy name or Array of string values of taxonomy names. - * @param array|string $args Change the order of the object IDs, either ASC or DESC. + * @param array|string $args { + * Change the order of the object IDs. + * + * @type string $order Order to retrieve terms. Accepts 'ASC' or 'DESC'. Default 'ASC'. + * } * @return string[]|WP_Error An array of object IDs as numeric strings on success, * WP_Error if the taxonomy does not exist. */ diff --git a/wp-includes/version.php b/wp-includes/version.php index b3991da34c..1c41b757ce 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-alpha-55692'; +$wp_version = '6.3-alpha-55693'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.