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

@@ -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 ) {

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 );
 

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
  *

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 ) ) {

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 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.
 		 * @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.

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 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 );
 }

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.