From 7004afe4f4bac1fd17a142051832bdf6be8e6fcf Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Mon, 16 Mar 2020 18:40:07 +0000 Subject: [PATCH] Docs: Various docblock corrections and improvements. See #49572 Built from https://develop.svn.wordpress.org/trunk@47461 git-svn-id: http://core.svn.wordpress.org/trunk@47248 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/class-custom-image-header.php | 2 +- wp-admin/includes/image.php | 8 +++++++- wp-includes/formatting.php | 12 ++++++------ wp-includes/functions.php | 9 ++++++++- wp-includes/pluggable.php | 12 ++++++------ wp-includes/post.php | 4 ++-- wp-includes/version.php | 2 +- 7 files changed, 31 insertions(+), 18 deletions(-) diff --git a/wp-admin/includes/class-custom-image-header.php b/wp-admin/includes/class-custom-image-header.php index 8f005b164b..841dccc319 100644 --- a/wp-admin/includes/class-custom-image-header.php +++ b/wp-admin/includes/class-custom-image-header.php @@ -1244,7 +1244,7 @@ endif; * @since 3.9.0 * * @param array $object Attachment object. - * @param string $cropped Cropped image URL. + * @param string $cropped File path to cropped image. * @return int Attachment ID. */ final public function insert_attachment( $object, $cropped ) { diff --git a/wp-admin/includes/image.php b/wp-admin/includes/image.php index f9108091fc..697feadf97 100644 --- a/wp-admin/includes/image.php +++ b/wp-admin/includes/image.php @@ -533,7 +533,13 @@ function wp_generate_attachment_metadata( $attachment_id, $file ) { * * @param array $image_attachment An array of parameters to create the thumbnail. * @param array $metadata Current attachment metadata. - * @param array $uploaded An array containing the thumbnail path and url. + * @param array $uploaded { + * Information about the newly-uploaded file. + * + * @type string $file Filename of the newly-uploaded file. + * @type string $url URL of the uploaded file. + * @type string $type File type. + * } */ $image_attachment = apply_filters( 'attachment_thumbnail_args', $image_attachment, $metadata, $uploaded ); diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php index 5dca162788..f093c915e8 100644 --- a/wp-includes/formatting.php +++ b/wp-includes/formatting.php @@ -3499,7 +3499,7 @@ function _wp_iso_convert( $match ) { } /** - * Given a date in the timezone of the site, returns that date in UTC timezone. + * Given a date in the timezone of the site, returns that date in UTC. * * Requires and returns a date in the Y-m-d H:i:s format. * Return format can be overridden using the $format parameter. @@ -3508,7 +3508,7 @@ function _wp_iso_convert( $match ) { * * @param string $string The date to be converted, in the timezone of the site. * @param string $format The format string for the returned date. Default 'Y-m-d H:i:s'. - * @return string Formatted version of the date, in UTC timezone. + * @return string Formatted version of the date, in UTC. */ function get_gmt_from_date( $string, $format = 'Y-m-d H:i:s' ) { $datetime = date_create( $string, wp_timezone() ); @@ -3521,14 +3521,14 @@ function get_gmt_from_date( $string, $format = 'Y-m-d H:i:s' ) { } /** - * Given a date in UTC timezone, returns that date in the timezone of the site. + * Given a date in UTC or GMT timezone, returns that date in the timezone of the site. * * Requires and returns a date in the Y-m-d H:i:s format. * Return format can be overridden using the $format parameter. * * @since 1.2.0 * - * @param string $string The date to be converted, in UTC timezone. + * @param string $string The date to be converted, in UTC or GMT timezone. * @param string $format The format string for the returned date. Default 'Y-m-d H:i:s'. * @return string Formatted version of the date, in the site's timezone. */ @@ -3543,7 +3543,7 @@ function get_date_from_gmt( $string, $format = 'Y-m-d H:i:s' ) { } /** - * Computes an offset in seconds from an iso8601 timezone. + * Given an ISO 8601 timezone, returns its UTC offset in seconds. * * @since 1.5.0 * @@ -3564,7 +3564,7 @@ function iso8601_timezone_to_offset( $timezone ) { } /** - * Converts an iso8601 (Ymd\TH:i:sO) date to MySQL DateTime (Y-m-d H:i:s) format used by post_date[_gmt]. + * Given an ISO 8601 (Ymd\TH:i:sO) date, returns a MySQL DateTime (Y-m-d H:i:s) format used by post_date[_gmt]. * * @since 1.5.0 * diff --git a/wp-includes/functions.php b/wp-includes/functions.php index dad7f15862..321ec60168 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -2616,7 +2616,14 @@ function _wp_check_existing_file_names( $filename, $files ) { * @param null|string $deprecated Never used. Set to null. * @param string $bits File content * @param string $time Optional. Time formatted in 'yyyy/mm'. Default null. - * @return array + * @return array { + * Information about the newly-uploaded file. + * + * @type string $file Filename of the newly-uploaded file. + * @type string $url URL of the uploaded file. + * @type string $type File type. + * @type string|false $error Error message, if there has been an error. + * } */ function wp_upload_bits( $name, $deprecated, $bits, $time = null ) { if ( ! empty( $deprecated ) ) { diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index 3de1934044..2a7993d64b 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -2643,7 +2643,7 @@ if ( ! function_exists( 'get_avatar' ) ) : } /** - * Filters whether to retrieve the avatar URL early. + * Allows the HTML for a user's avatar to be returned early. * * Passing a non-null value will effectively short-circuit get_avatar(), passing * the value through the {@see 'get_avatar'} filter and returning early. @@ -2651,7 +2651,7 @@ if ( ! function_exists( 'get_avatar' ) ) : * @since 4.2.0 * * @param string|null $avatar HTML for the user's avatar. Default null. - * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash, + * @param mixed $id_or_email The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. * @param array $args Arguments passed to get_avatar_url(), after processing. */ @@ -2702,17 +2702,17 @@ if ( ! function_exists( 'get_avatar' ) ) : ); /** - * Filters the avatar to retrieve. + * Filters the HTML for a user's avatar. * * @since 2.5.0 * @since 4.2.0 The `$args` parameter was added. * - * @param string $avatar <img> tag for the user's avatar. - * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash, + * @param string $avatar HTML for the user's avatar. + * @param mixed $id_or_email The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. * @param int $size Square avatar width and height in pixels to retrieve. * @param string $default URL for the default image or a default type. Accepts '404', 'retro', 'monsterid', - * 'wavatar', 'indenticon','mystery' (or 'mm', or 'mysteryman'), 'blank', or 'gravatar_default'. + * 'wavatar', 'indenticon', 'mystery', 'mm', 'mysteryman', 'blank', or 'gravatar_default'. * Default is the value of the 'avatar_default' option, with a fallback of 'mystery'. * @param string $alt Alternative text to use in the avatar image tag. Default empty. * @param array $args Arguments passed to get_avatar_data(), after processing. diff --git a/wp-includes/post.php b/wp-includes/post.php index 38582f2fa4..e8e6732dc7 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -515,8 +515,8 @@ function get_attached_file( $attachment_id, $unfiltered = false ) { * * @since 2.1.0 * - * @param string $file Path to attached file. - * @param int $attachment_id Attachment ID. + * @param string|false $file The file path to where the attached file should be, false otherwise. + * @param int $attachment_id Attachment ID. */ return apply_filters( 'get_attached_file', $file, $attachment_id ); } diff --git a/wp-includes/version.php b/wp-includes/version.php index 04df4efab8..9ee85d2adf 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -13,7 +13,7 @@ * * @global string $wp_version */ -$wp_version = '5.5-alpha-47459'; +$wp_version = '5.5-alpha-47461'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.