From a2e08032dce12cddeb93e3b2d57fb1a73f0d4fb9 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sat, 26 Oct 2019 20:42:00 +0000 Subject: [PATCH] Docs: Miscellaneous docblock fixes and improvements. See #48303 git-svn-id: https://develop.svn.wordpress.org/trunk@46594 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/post.php | 29 ++++--- src/wp-admin/user-new.php | 2 +- .../class-wp-block-styles-registry.php | 6 +- src/wp-includes/class-wp-image-editor-gd.php | 8 +- .../class-wp-image-editor-imagick.php | 8 +- src/wp-includes/functions.php | 8 +- src/wp-includes/media.php | 84 +++++++++++++------ 7 files changed, 101 insertions(+), 44 deletions(-) diff --git a/src/wp-admin/includes/post.php b/src/wp-admin/includes/post.php index 7ff33e3bb8..b659254c1f 100644 --- a/src/wp-admin/includes/post.php +++ b/src/wp-admin/includes/post.php @@ -1319,7 +1319,12 @@ function postbox_classes( $box_id, $screen_id ) { * @param int $id Post ID or post object. * @param string $title Optional. Title to override the post's current title when generating the post name. Default null. * @param string $name Optional. Name to override the post name. Default null. - * @return array Array containing the sample permalink with placeholder for the post name, and the post name. + * @return array { + * Array containing the sample permalink with placeholder for the post name, and the post name. + * + * @type string $0 The permalink with placeholder for the post name. + * @type string $1 The post name. + * } */ function get_sample_permalink( $id, $title = null, $name = null ) { $post = get_post( $id ); @@ -1383,7 +1388,12 @@ function get_sample_permalink( $id, $title = null, $name = null ) { * * @since 4.4.0 * - * @param array $permalink Array containing the sample permalink with placeholder for the post name, and the post name. + * @param array $permalink { + * Array containing the sample permalink with placeholder for the post name, and the post name. + * + * @type string $0 The permalink with placeholder for the post name. + * @type string $1 The post name. + * } * @param int $post_id Post ID. * @param string $title Post title. * @param string $name Post name (slug). @@ -1637,17 +1647,16 @@ function _admin_notice_post_locked() { } if ( $user ) { - /** * Filters whether to show the post locked dialog. * - * Returning a falsey value to the filter will short-circuit displaying the dialog. + * Returning false from the filter will prevent the dialog from being displayed. * * @since 3.6.0 * - * @param bool $display Whether to display the dialog. Default true. - * @param WP_Post $post Post object. - * @param WP_User|bool $user WP_User object on success, false otherwise. + * @param bool $display Whether to display the dialog. Default true. + * @param WP_Post $post Post object. + * @param WP_User $user The user with the lock for the post. */ if ( ! apply_filters( 'show_post_locked_dialog', true, $post, $user ) ) { return; @@ -1696,14 +1705,14 @@ function _admin_notice_post_locked() { /** * Filters whether to allow the post lock to be overridden. * - * Returning a falsey value to the filter will disable the ability + * Returning false from the filter will disable the ability * to override the post lock. * * @since 3.6.0 * - * @param bool $override Whether to allow overriding post locks. Default true. + * @param bool $override Whether to allow the post lock to be overridden. Default true. * @param WP_Post $post Post object. - * @param WP_User $user User object. + * @param WP_User $user The user with the lock for the post. */ $override = apply_filters( 'override_post_lock', true, $post, $user ); $tab_last = $override ? '' : ' wp-tab-last'; diff --git a/src/wp-admin/user-new.php b/src/wp-admin/user-new.php index d8c76e6758..2abd094519 100644 --- a/src/wp-admin/user-new.php +++ b/src/wp-admin/user-new.php @@ -105,7 +105,7 @@ if ( isset( $_REQUEST['action'] ) && 'adduser' == $_REQUEST['action'] ) { * @since 4.4.0 * * @param int $user_id The invited user's ID. - * @param array $role The role of invited user. + * @param array $role Array containing role information for the invited user. * @param string $newuser_key The key of the invitation. */ do_action( 'invite_user', $user_id, $role, $newuser_key ); diff --git a/src/wp-includes/class-wp-block-styles-registry.php b/src/wp-includes/class-wp-block-styles-registry.php index 32496321c6..51d33c14ed 100644 --- a/src/wp-includes/class-wp-block-styles-registry.php +++ b/src/wp-includes/class-wp-block-styles-registry.php @@ -67,7 +67,7 @@ final class WP_Block_Styles_Registry { * Unregisters a block style. * * @param string $block_name Block type name including namespace. - * @param array $block_style_name Block style name. + * @param string $block_style_name Block style name. * * @return boolean True if the block style was unregistered with success and false otherwise. */ @@ -90,7 +90,7 @@ final class WP_Block_Styles_Registry { * @since 5.3.0 * * @param string $block_name Block type name including namespace. - * @param array $block_style_name Block style name. + * @param string $block_style_name Block style name. * * @return array Registered block style properties. */ @@ -135,7 +135,7 @@ final class WP_Block_Styles_Registry { * @since 5.3.0 * * @param string $block_name Block type name including namespace. - * @param array $block_style_name Block style name. + * @param string $block_style_name Block style name. * * @return bool True if the block style is registered, false otherwise. */ diff --git a/src/wp-includes/class-wp-image-editor-gd.php b/src/wp-includes/class-wp-image-editor-gd.php index 53cf2ef9be..8cfee31f90 100644 --- a/src/wp-includes/class-wp-image-editor-gd.php +++ b/src/wp-includes/class-wp-image-editor-gd.php @@ -245,7 +245,13 @@ class WP_Image_Editor_GD extends WP_Image_Editor { * * @since 5.3.0 * - * @param array $size_data Array of width, height, and whether to crop. + * @param array $size_data { + * Array of size data. + * + * @type int $width The maximum width in pixels. + * @type int $height The maximum height in pixels. + * @type bool $crop Whether to crop the image to exact dimensions. + * } * @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta. */ public function make_subsize( $size_data ) { diff --git a/src/wp-includes/class-wp-image-editor-imagick.php b/src/wp-includes/class-wp-image-editor-imagick.php index c014696b38..99c568d569 100644 --- a/src/wp-includes/class-wp-image-editor-imagick.php +++ b/src/wp-includes/class-wp-image-editor-imagick.php @@ -453,7 +453,13 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor { * * @since 5.3.0 * - * @param array $size_data Array of width, height, and whether to crop. + * @param array $size_data { + * Array of size data. + * + * @type int $width The maximum width in pixels. + * @type int $height The maximum height in pixels. + * @type bool $crop Whether to crop the image to exact dimensions. + * } * @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta. */ public function make_subsize( $size_data ) { diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php index e7216f99ca..1c185516a1 100644 --- a/src/wp-includes/functions.php +++ b/src/wp-includes/functions.php @@ -2857,7 +2857,9 @@ function wp_get_image_mime( $file ) { * Retrieve list of mime types and file extensions. * * @since 3.5.0 - * @since 4.2.0 Support was added for GIMP (xcf) files. + * @since 4.2.0 Support was added for GIMP (.xcf) files. + * @since 4.9.2 Support was added for Flac (.flac) files. + * @since 4.9.6 Support was added for AAC (.aac) files. * * @return array Array of mime types keyed by the file extension regex corresponding to those types. */ @@ -3042,9 +3044,7 @@ function get_allowed_mime_types( $user = null ) { * * @since 2.0.0 * - * @param array $t Mime types keyed by the file extension regex corresponding to - * those types. 'swf' and 'exe' removed from full list. 'htm|html' also - * removed depending on '$user' capabilities. + * @param array $t Mime types keyed by the file extension regex corresponding to those types. * @param int|WP_User|null $user User ID, User object or null if not provided (indicates current user). */ return apply_filters( 'upload_mimes', $t, $user ); diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php index 002581e174..4b8f608fd2 100644 --- a/src/wp-includes/media.php +++ b/src/wp-includes/media.php @@ -38,10 +38,7 @@ function wp_get_additional_image_sizes() { * not set. * * Finally, there is a filter named {@see 'editor_max_image_size'}, that will be - * called on the calculated array for width and height, respectively. The second - * parameter will be the value that was in the $size parameter. The returned - * type for the hook is an array with the width as the first element and the - * height as the second element. + * called on the calculated array for width and height, respectively. * * @since 2.5.0 * @@ -54,7 +51,12 @@ function wp_get_additional_image_sizes() { * Default 'medium'. * @param string $context Optional. Could be 'display' (like in a theme) or 'edit' * (like inserting into an editor). Default null. - * @return array Width and height of what the result image should resize to. + * @return int[] { + * An array of width and height values. + * + * @type int $0 The maximum width in pixels. + * @type int $1 The maximum height in pixels. + * } */ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $context = null ) { global $content_width; @@ -117,8 +119,12 @@ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $co * * @since 2.5.0 * - * @param array $max_image_size An array with the width as the first element, - * and the height as the second element. + * @param int[] $max_image_size { + * An array of width and height values. + * + * @type int $0 The maximum width in pixels. + * @type int $1 The maximum height in pixels. + * } * @param string|array $size Size of what the result image should be. * @param string $context The context the image is being resized for. * Possible values are 'display' (like in a theme) @@ -417,7 +423,12 @@ function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) { * @param int $current_height Current height of the image. * @param int $max_width Optional. Max width in pixels to constrain to. Default 0. * @param int $max_height Optional. Max height in pixels to constrain to. Default 0. - * @return array First item is the width, the second item is the height. + * @return int[] { + * An array of width and height values. + * + * @type int $0 The width in pixels. + * @type int $1 The height in pixels. + * } */ function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) { if ( ! $max_width && ! $max_height ) { @@ -474,7 +485,12 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width = * * @since 4.1.0 * - * @param array $dimensions The image width and height. + * @param int[] $dimensions { + * An array of width and height values. + * + * @type int $0 The width in pixels. + * @type int $1 The height in pixels. + * } * @param int $current_width The current width of the image. * @param int $current_height The current height of the image. * @param int $max_width The maximum width permitted. @@ -1149,10 +1165,15 @@ function wp_get_attachment_image_srcset( $attachment_id, $size = 'medium', $imag * * @since 4.4.0 * - * @param array $size_array Array of width and height values in pixels (in that order). + * @param int[] $size_array { + * An array of width and height values. + * + * @type int $0 The width in pixels. + * @type int $1 The height in pixels. + * } * @param string $image_src The 'src' of the image. * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. - * @param int $attachment_id Optional. The image attachment ID to pass to the filter. Default 0. + * @param int $attachment_id Optional. The image attachment ID. Default 0. * @return string|bool The 'srcset' attribute value. False on error or when only one source exists. */ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attachment_id = 0 ) { @@ -1162,7 +1183,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac * @since 4.5.0 * * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. - * @param array $size_array Array of width and height values in pixels (in that order). + * @param int[] $size_array { + * An array of requested width and height values. + * + * @type int $0 The width in pixels. + * @type int $1 The height in pixels. + * } * @param string $image_src The 'src' of the image. * @param int $attachment_id The image attachment ID or 0 if not supplied. */ @@ -1231,7 +1257,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac * @since 4.4.0 * * @param int $max_width The maximum image width to be included in the 'srcset'. Default '2048'. - * @param array $size_array Array of width and height values in pixels (in that order). + * @param int[] $size_array { + * An array of requested width and height values. + * + * @type int $0 The width in pixels. + * @type int $1 The height in pixels. + * } */ $max_srcset_image_width = apply_filters( 'max_srcset_image_width', 2048, $size_array ); @@ -1310,7 +1341,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac * pixel density value if paired with an 'x' descriptor. * } * } - * @param array $size_array Array of width and height values in pixels (in that order). + * @param array $size_array { + * An array of requested width and height values. + * + * @type int $0 The width in pixels. + * @type int $1 The height in pixels. + * } * @param string $image_src The 'src' of the image. * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. * @param int $attachment_id Image attachment ID or 0. @@ -2376,7 +2412,7 @@ function wp_mediaelement_fallback( $url ) { } /** - * Returns a filtered list of WP-supported audio formats. + * Returns a filtered list of supported audio formats. * * @since 3.6.0 * @@ -2624,7 +2660,7 @@ function wp_audio_shortcode( $attr, $content = '' ) { add_shortcode( 'audio', 'wp_audio_shortcode' ); /** - * Returns a filtered list of WP-supported video formats. + * Returns a filtered list of supported video formats. * * @since 3.6.0 * @@ -4011,9 +4047,9 @@ function get_attached_media( $type, $post = 0 ) { * * @since 3.6.0 * - * @param array $args Post query arguments. - * @param string $type Mime type of the desired media. - * @param mixed $post Post ID or object. + * @param array $args Post query arguments. + * @param string $type Mime type of the desired media. + * @param WP_Post $post Post object. */ $args = apply_filters( 'get_attached_media_args', $args, $type, $post ); @@ -4024,15 +4060,15 @@ function get_attached_media( $type, $post = 0 ) { * * @since 3.6.0 * - * @param array $children Associative array of media attached to the given post. - * @param string $type Mime type of the media desired. - * @param mixed $post Post ID or object. + * @param array $children Associative array of media attached to the given post. + * @param string $type Mime type of the media desired. + * @param WP_Post $post Post object. */ return (array) apply_filters( 'get_attached_media', $children, $type, $post ); } /** - * Check the content blob for an audio, video, object, embed, or iframe tags. + * Check the content HTML for a audio, video, object, embed, or iframe tags. * * @since 3.6.0 * @@ -4288,7 +4324,7 @@ function wpview_media_sandbox_styles() { } /** - * Registers the personal data exporter for media + * Registers the personal data exporter for media. * * @param array $exporters An array of personal data exporters. * @return array An array of personal data exporters.