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
This commit is contained in:
John Blackbourn 2020-03-16 18:40:07 +00:00
parent 0a08229a9b
commit 7004afe4f4
7 changed files with 31 additions and 18 deletions

View File

@ -1244,7 +1244,7 @@ endif;
* @since 3.9.0 * @since 3.9.0
* *
* @param array $object Attachment object. * @param array $object Attachment object.
* @param string $cropped Cropped image URL. * @param string $cropped File path to cropped image.
* @return int Attachment ID. * @return int Attachment ID.
*/ */
final public function insert_attachment( $object, $cropped ) { final public function insert_attachment( $object, $cropped ) {

View File

@ -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 $image_attachment An array of parameters to create the thumbnail.
* @param array $metadata Current attachment metadata. * @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 ); $image_attachment = apply_filters( 'attachment_thumbnail_args', $image_attachment, $metadata, $uploaded );

View File

@ -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. * Requires and returns a date in the Y-m-d H:i:s format.
* Return format can be overridden using the $format parameter. * 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 $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'. * @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' ) { function get_gmt_from_date( $string, $format = 'Y-m-d H:i:s' ) {
$datetime = date_create( $string, wp_timezone() ); $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. * Requires and returns a date in the Y-m-d H:i:s format.
* Return format can be overridden using the $format parameter. * Return format can be overridden using the $format parameter.
* *
* @since 1.2.0 * @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'. * @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. * @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 * @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 * @since 1.5.0
* *

View File

@ -2616,7 +2616,14 @@ function _wp_check_existing_file_names( $filename, $files ) {
* @param null|string $deprecated Never used. Set to null. * @param null|string $deprecated Never used. Set to null.
* @param string $bits File content * @param string $bits File content
* @param string $time Optional. Time formatted in 'yyyy/mm'. Default null. * @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 ) { function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
if ( ! empty( $deprecated ) ) { if ( ! empty( $deprecated ) ) {

View File

@ -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 * Passing a non-null value will effectively short-circuit get_avatar(), passing
* the value through the {@see 'get_avatar'} filter and returning early. * the value through the {@see 'get_avatar'} filter and returning early.
@ -2651,7 +2651,7 @@ if ( ! function_exists( 'get_avatar' ) ) :
* @since 4.2.0 * @since 4.2.0
* *
* @param string|null $avatar HTML for the user's avatar. Default null. * @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. * user email, WP_User object, WP_Post object, or WP_Comment object.
* @param array $args Arguments passed to get_avatar_url(), after processing. * @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 2.5.0
* @since 4.2.0 The `$args` parameter was added. * @since 4.2.0 The `$args` parameter was added.
* *
* @param string $avatar <img> tag for the user's avatar. * @param string $avatar HTML for the user's avatar.
* @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. * 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 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', * @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'. * 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 string $alt Alternative text to use in the avatar image tag. Default empty.
* @param array $args Arguments passed to get_avatar_data(), after processing. * @param array $args Arguments passed to get_avatar_data(), after processing.

View File

@ -515,8 +515,8 @@ function get_attached_file( $attachment_id, $unfiltered = false ) {
* *
* @since 2.1.0 * @since 2.1.0
* *
* @param string $file Path to attached file. * @param string|false $file The file path to where the attached file should be, false otherwise.
* @param int $attachment_id Attachment ID. * @param int $attachment_id Attachment ID.
*/ */
return apply_filters( 'get_attached_file', $file, $attachment_id ); return apply_filters( 'get_attached_file', $file, $attachment_id );
} }

View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.