Docs: Corrections and improvements to types used in docblocks for symbols, properties, and filters.

See #53399

Built from https://develop.svn.wordpress.org/trunk@51298


git-svn-id: http://core.svn.wordpress.org/trunk@50907 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/block-editor.php

@@ -244,7 +244,7 @@ function get_legacy_widget_block_editor_settings() {
 	 *
 	 * @since 5.8.0
 	 *
-	 * @param array $widgets An array of excluded widget-type IDs.
+	 * @param string[] $widgets An array of excluded widget-type IDs.
 	 */
 	$editor_settings['widgetTypesToHideFromLegacyWidgetBlock'] = apply_filters(
 		'widget_types_to_hide_from_legacy_widget_block',
@@ -394,7 +394,7 @@ function get_block_editor_settings( array $custom_settings, $block_editor_contex
  *
  * @global WP_Post $post Global post object.
  *
- * @param array                   $preload_paths        List of paths to preload.
+ * @param string[]                $preload_paths        List of paths to preload.
  * @param WP_Block_Editor_Context $block_editor_context The current block editor context.
  *
  * @return void

wp-includes/block-supports/border.php

@@ -125,7 +125,7 @@ function wp_apply_border_support( $block_type, $block_attributes ) {
  *
  * @param WP_Block_Type $block_type Block type.
  *
- * @return boolean
+ * @return bool
  */
 function wp_skip_border_serialization( $block_type ) {
 	$border_support = _wp_array_get( $block_type->supports, array( '__experimentalBorder' ), false );
@@ -149,8 +149,7 @@ function wp_skip_border_serialization( $block_type ) {
  * @param WP_Block_Type $block_type Block type to check for support.
  * @param string        $feature    Name of the feature to check support for.
  * @param mixed         $default    Fallback value for feature support, defaults to false.
- *
+ * @return bool Whether the feature is supported.
- * @return boolean Whether or not the feature is supported.
  */
 function wp_has_border_feature_support( $block_type, $feature, $default = false ) {
 	// Check if all border support features have been opted into via `"__experimentalBorder": true`.

wp-includes/block-supports/spacing.php

@@ -75,9 +75,8 @@ function wp_apply_spacing_support( $block_type, $block_attributes ) {
  *
  * @param WP_Block_Type $block_type Block type to check for support.
  * @param string        $feature    Name of the feature to check support for.
- * @param mixed         $default    Fallback value for feature support, defaults to false.
+ * @param mixed         $default    Fallback value for feature support. Default false.
- *
+ * @return bool Whether the feature is supported.
- * @return boolean                  Whether or not the feature is supported.
  */
 function wp_has_spacing_feature_support( $block_type, $feature, $default = false ) {
 	// Check if the specific feature has been opted into individually

wp-includes/block-template.php

@@ -16,7 +16,7 @@
  *
  * @param string   $template  Path to the template. See locate_template().
  * @param string   $type      Sanitized filename without extension.
- * @param array  $templates A list of template candidates, in descending order of priority.
+ * @param string[] $templates A list of template candidates, in descending order of priority.
  * @return string The path to the Full Site Editing template canvas file, or the fallback PHP template.
  */
 function locate_block_template( $template, $type, array $templates ) {

wp-includes/blocks.php

@@ -960,9 +960,8 @@ function unregister_block_style( $block_name, $block_style_name ) {
  *
  * @param WP_Block_Type $block_type Block type to check for support.
  * @param string        $feature    Name of the feature to check support for.
- * @param mixed         $default    Fallback value for feature support, defaults to false.
+ * @param mixed         $default    Optional. Fallback value for feature support. Default false.
- *
+ * @return bool Whether the feature is supported.
- * @return boolean                  Whether or not the feature is supported.
  */
 function block_has_support( $block_type, $feature, $default = false ) {
 	$block_support = $default;

wp-includes/class-wp-block.php

@@ -61,7 +61,7 @@ class WP_Block {
 	 * List of inner blocks (of this same class)
 	 *
 	 * @since 5.5.0
-	 * @var WP_Block[]
+	 * @var WP_Block_List
 	 */
 	public $inner_blocks = array();
 

wp-includes/class-wp-comment-query.php

@@ -214,7 +214,7 @@ class WP_Comment_Query {
 	 *     @type string|array $post_status               Post status or array of post statuses to retrieve
 	 *                                                   affiliated comments for. Pass 'any' to match any value.
 	 *                                                   Default empty.
-	 *     @type string       $post_type                 Post type or array of post types to retrieve affiliated
+	 *     @type string|array $post_type                 Post type or array of post types to retrieve affiliated
 	 *                                                   comments for. Pass 'any' to match any value. Default empty.
 	 *     @type string       $post_name                 Post name to retrieve affiliated comments for.
 	 *                                                   Default empty.

wp-includes/class-wp-http-streams.php

@@ -365,7 +365,7 @@ class WP_Http_Streams {
 	 *
 	 * @since 3.7.0
 	 *
-	 * @param stream $stream The PHP Stream which the SSL request is being made over
+	 * @param resource $stream The PHP Stream which the SSL request is being made over
 	 * @param string   $host   The hostname being requested
 	 * @return bool If the cerficiate presented in $stream is valid for $host
 	 */

wp-includes/class-wp-image-editor-gd.php

@@ -533,7 +533,7 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
 	 *
 	 * @since 3.5.0
 	 *
-	 * @param string|stream $filename
+	 * @param string   $filename
 	 * @param callable $function
 	 * @param array    $arguments
 	 * @return bool

wp-includes/class-wp-image-editor-imagick.php

@@ -901,7 +901,7 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor {
 	 *
 	 * @since 5.6.0
 	 *
-	 * @return true|WP_error
+	 * @return true|WP_Error
 	 */
 	protected function pdf_load_source() {
 		$filename = $this->pdf_setup();

wp-includes/class-wp-image-editor.php

@@ -505,7 +505,7 @@ abstract class WP_Image_Editor {
 	 *
 	 * @since 3.5.0
 	 *
-	 * @param string|stream $filename
+	 * @param string   $filename
 	 * @param callable $function
 	 * @param array    $arguments
 	 * @return bool

wp-includes/class-wp-term-query.php

@@ -166,8 +166,8 @@ class WP_Term_Query {
 	 *                                                terms are empty. Accepts 'all' or empty (disabled).
 	 *                                                Default empty.
 	 *     @type int          $child_of               Term ID to retrieve child terms of. If multiple taxonomies
-	 *                                                are passed, $child_of is ignored. Default 0.
+	 *                                                are passed, `$child_of` is ignored. Default 0.
-	 *     @type int|string   $parent                 Parent term ID to retrieve direct-child terms of.
+	 *     @type int          $parent                 Parent term ID to retrieve direct-child terms of.
 	 *                                                Default empty.
 	 *     @type bool         $childless              True to limit results to terms that have no children.
 	 *                                                This parameter has no effect on non-hierarchical taxonomies.

wp-includes/class-wp-theme-json.php

@@ -44,7 +44,7 @@ class WP_Theme_JSON {
 	 * The sources of data this object can represent.
 	 *
 	 * @since 5.8.0
-	 * @var array
+	 * @var string[]
 	 */
 	const VALID_ORIGINS = array(
 		'core',
@@ -166,7 +166,7 @@ class WP_Theme_JSON {
 
 	/**
 	 * @since 5.8.0
-	 * @var array
+	 * @var string[]
 	 */
 	const ALLOWED_TOP_LEVEL_KEYS = array(
 		'settings',
@@ -234,7 +234,7 @@ class WP_Theme_JSON {
 
 	/**
 	 * @since 5.8.0
-	 * @var array
+	 * @var string[]
 	 */
 	const ELEMENTS = array(
 		'link' => 'a',

wp-includes/customize/class-wp-customize-background-image-setting.php

@@ -20,7 +20,7 @@ final class WP_Customize_Background_Image_Setting extends WP_Customize_Setting {
 	/**
 	 * @since 3.4.0
 	 *
-	 * @param $value
+	 * @param mixed $value
 	 */
 	public function update( $value ) {
 		remove_theme_mod( 'background_image_thumb' );

wp-includes/customize/class-wp-customize-header-image-setting.php

@@ -24,7 +24,7 @@ final class WP_Customize_Header_Image_Setting extends WP_Customize_Setting {
 	 *
 	 * @global Custom_Image_Header $custom_image_header
 	 *
-	 * @param $value
+	 * @param mixed $value
 	 */
 	public function update( $value ) {
 		global $custom_image_header;

wp-includes/embed.php

@@ -724,7 +724,7 @@ function wp_oembed_ensure_format( $format ) {
  * @since 4.4.0
  *
  * @param bool             $served  Whether the request has already been served.
- * @param WP_HTTP_ResponseInterface $result  Result to send to the client. Usually a WP_REST_Response.
+ * @param WP_HTTP_Response $result  Result to send to the client. Usually a `WP_REST_Response`.
  * @param WP_REST_Request  $request Request used to generate the response.
  * @param WP_REST_Server   $server  Server instance.
  * @return true

wp-includes/general-template.php

@@ -1290,7 +1290,7 @@ function _wp_render_title_tag() {
  *                            Default '»'.
  * @param bool   $display     Optional. Whether to display or retrieve title. Default true.
  * @param string $seplocation Optional. Location of the separator ('left' or 'right').
- * @return string|null String on retrieve, null when displaying.
+ * @return string|void String when `$display` is true, nothing otherwise.
  */
 function wp_title( $sep = '»', $display = true, $seplocation = '' ) {
 	global $wp_locale;

wp-includes/l10n.php

@@ -401,7 +401,6 @@ function _x( $text, $context, $domain = 'default' ) {
  * @param string $context Context information for the translators.
  * @param string $domain  Optional. Text domain. Unique identifier for retrieving translated strings.
  *                        Default 'default'.
- * @return string Translated context string without pipe.
  */
 function _ex( $text, $context, $domain = 'default' ) {
 	echo _x( $text, $context, $domain );

wp-includes/post.php

@@ -1233,7 +1233,7 @@ function get_post_status_object( $post_status ) {
  * @param string       $operator Optional. The logical operation to perform. 'or' means only one element
  *                               from the array needs to match; 'and' means all elements must match.
  *                               Default 'and'.
- * @return array A list of post status names or objects.
+ * @return string[]|stdClass[] A list of post status names or objects.
  */
 function get_post_stati( $args = array(), $output = 'names', $operator = 'and' ) {
 	global $wp_post_statuses;
@@ -1427,7 +1427,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
  *                                               of a Dashicons helper class to use a font icon, e.g.
  *                                               'dashicons-chart-pie'. Pass 'none' to leave div.wp-menu-image empty
  *                                               so an icon can be added via CSS. Defaults to use the posts icon.
- *     @type string       $capability_type       The string to use to build the read, edit, and delete capabilities.
+ *     @type string|array $capability_type       The string to use to build the read, edit, and delete capabilities.
  *                                               May be passed as an array to allow for alternative plurals when using
  *                                               this argument as a base to construct the capabilities, e.g.
  *                                               array('story', 'stories'). Default 'post'.
@@ -3794,7 +3794,7 @@ function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) {
  *     @type string $post_date             The date of the post. Default is the current time.
  *     @type string $post_date_gmt         The date of the post in the GMT timezone. Default is
  *                                         the value of `$post_date`.
- *     @type mixed  $post_content          The post content. Default empty.
+ *     @type string $post_content          The post content. Default empty.
  *     @type string $post_content_filtered The filtered post content. Default empty.
  *     @type string $post_title            The post title. Default empty.
  *     @type string $post_excerpt          The post excerpt. Default empty.

wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php

@@ -37,7 +37,7 @@ class WP_REST_Autosaves_Controller extends WP_REST_Revisions_Controller {
 	 * Revision controller.
 	 *
 	 * @since 5.0.0
-	 * @var WP_REST_Controller
+	 * @var WP_REST_Revisions_Controller
 	 */
 	private $revisions_controller;
 

wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php

@@ -476,7 +476,7 @@ class WP_REST_Templates_Controller extends WP_REST_Controller {
 	 *
 	 * @since 5.8.0
 	 *
-	 * @return array List of link relations.
+	 * @return string[] List of link relations.
 	 */
 	protected function get_available_actions() {
 		$rels = array();

wp-includes/user.php

@@ -2442,7 +2442,7 @@ function _get_additional_user_keys( $user ) {
  *
  * @since 3.7.0
  *
- * @param WP_User $user Optional. WP_User object.
+ * @param WP_User|null $user Optional. WP_User object.
  * @return string[] Array of contact method labels keyed by contact method.
  */
 function wp_get_user_contact_methods( $user = null ) {
@@ -2461,7 +2461,7 @@ function wp_get_user_contact_methods( $user = null ) {
 	 * @since 2.9.0
 	 *
 	 * @param string[]     $methods Array of contact method labels keyed by contact method.
-	 * @param WP_User  $user    WP_User object.
+	 * @param WP_User|null $user    WP_User object or null if none was provided.
 	 */
 	return apply_filters( 'user_contactmethods', $methods, $user );
 }
@@ -2474,7 +2474,7 @@ function wp_get_user_contact_methods( $user = null ) {
  * @since 2.9.0
  * @access private
  *
- * @param WP_User $user Optional. WP_User object. Default null.
+ * @param WP_User|null $user Optional. WP_User object. Default null.
  * @return string[] Array of contact method labels keyed by contact method.
  */
 function _wp_get_user_contactmethods( $user = null ) {

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-alpha-51297';
+$wp_version = '5.9-alpha-51298';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/widgets.php

@@ -1828,7 +1828,7 @@ function wp_setup_widgets_block_editor() {
  *
  * @since 5.8.0
  *
- * @return boolean Whether or not to use the block editor to manage widgets.
+ * @return bool Whether to use the block editor to manage widgets.
  */
 function wp_use_widgets_block_editor() {
 	/**
@@ -1836,7 +1836,7 @@ function wp_use_widgets_block_editor() {
 	 *
 	 * @since 5.8.0
 	 *
-	 * @param boolean $use_widgets_block_editor Whether or not to use the block editor to manage widgets.
+	 * @param bool $use_widgets_block_editor Whether to use the block editor to manage widgets.
 	 */
 	return apply_filters(
 		'use_widgets_block_editor',

wp-includes/wp-db.php

@@ -1007,7 +1007,7 @@ class wpdb {
 	 *                        then the custom users and usermeta tables will be mapped. Default true.
 	 * @param int    $blog_id Optional. The blog_id to prefix. Used only when prefix is requested.
 	 *                        Defaults to wpdb::$blogid.
-	 * @return array Table names. When a prefix is requested, the key is the unprefixed table name.
+	 * @return string[] Table names. When a prefix is requested, the key is the unprefixed table name.
 	 */
 	public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) {
 		switch ( $scope ) {