Docs: Correct and improve the docs for some media related functions.

See #48303
Built from https://develop.svn.wordpress.org/trunk@47394


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

wp-includes/media.php

@@ -166,27 +166,28 @@ function image_hwstring( $width, $height ) {
 /**
  * Scale an image to fit a particular size (such as 'thumb' or 'medium').
  *
- * Array with image url, width, height, and whether is intermediate size, in
- * that order is returned on success is returned. $is_intermediate is true if
- * $url is a resized image, false if it is the original.
- *
  * The URL might be the original image, or it might be a resized version. This
  * function won't create a new resized copy, it will just return an already
  * resized one if it exists.
  *
  * A plugin may use the {@see 'image_downsize'} filter to hook into and offer image
  * resizing services for images. The hook must return an array with the same
- * elements that are returned in the function. The first element being the URL
+ * elements that are normally returned from the function.
- * to the new image that was resized.
  *
  * @since 2.5.0
  *
  * @param int          $id   Attachment ID for image.
- * @param array|string $size Optional. Image size to scale to. Accepts any valid image size,
+ * @param string|int[] $size Optional. Image size to scale to. Accepts any valid image size name,
  *                           or an array of width and height values in pixels (in that order).
  *                           Default 'medium'.
- * @return array|false Array containing the image URL, width, height, and boolean for whether
+ * @return array|false {
- *                     the image is an intermediate size. False on failure.
+ *     Array of image data, or boolean false if no image is available.
+ *
+ *     @type string $0 Image source URL.
+ *     @type int    $1 Image width in pixels.
+ *     @type int    $2 Image height in pixels.
+ *     @type bool   $3 Whether the image is a resized image.
+ * }
  */
 function image_downsize( $id, $size = 'medium' ) {
 	$is_image = wp_attachment_is_image( $id );
@@ -194,15 +195,15 @@ function image_downsize( $id, $size = 'medium' ) {
 	/**
 	 * Filters whether to preempt the output of image_downsize().
 	 *
-	 * Passing a truthy value to the filter will effectively short-circuit
+	 * Returning a truthy value from the filter will effectively short-circuit
-	 * down-sizing the image, returning that value as output instead.
+	 * down-sizing the image, returning that value instead.
 	 *
 	 * @since 2.5.0
 	 *
-	 * @param bool         $downsize Whether to short-circuit the image downsize. Default false.
+	 * @param bool|array   $downsize Whether to short-circuit the image downsize.
 	 * @param int          $id       Attachment ID for image.
-	 * @param array|string $size     Size of image. Image size or array of width and height values (in that order).
+	 * @param array|string $size     Requested size of image. Image size name, or array of width
-	 *                               Default 'medium'.
+	 *                               and height values (in that order).
 	 */
 	$out = apply_filters( 'image_downsize', false, $id, $size );
 
@@ -932,22 +933,21 @@ function wp_get_registered_image_subsizes() {
 }
 
 /**
- * Retrieve an image to represent an attachment.
+ * Retrieves an image to represent an attachment.
- *
- * A mime icon for files, thumbnail or intermediate size for images.
- *
- * The returned array contains four values: the URL of the attachment image src,
- * the width of the image file, the height of the image file, and a boolean
- * representing whether the returned array describes an intermediate (generated)
- * image size or the original, full-sized upload.
  *
  * @since 2.5.0
  *
  * @param int          $attachment_id Image attachment ID.
- * @param string|array $size          Optional. Image size. Accepts any valid image size, or an array of width
+ * @param string|int[] $size          Optional. Image size. Accepts any valid image size name, or an array of width
  *                                    and height values in pixels (in that order). Default 'thumbnail'.
- * @param bool         $icon          Optional. Whether the image should be treated as an icon. Default false.
+ * @param bool         $icon          Optional. Whether the image should fall back to a mime type icon. Default false.
- * @return array|false Returns an array (url, width, height, is_intermediate), or false if no image is available.
+ * @return array|false {
+ *     Array of image data, or boolean false if no image is available.
+ *
+ *     @type string $0 Image source URL.
+ *     @type int    $1 Image width in pixels.
+ *     @type int    $2 Image height in pixels.
+ * }
  */
 function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon = false ) {
 	// Get a thumbnail or intermediate image if there is one.
@@ -972,15 +972,21 @@ function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon
 		}
 	}
 	/**
-	 * Filters the image src result.
+	 * Filters the attachment image source result.
 	 *
 	 * @since 4.3.0
 	 *
-	 * @param array|false  $image         Either array with src, width & height, icon src, or false.
+	 * @param array|false  $image         {
+	 *     Array of image data, or boolean false if no image is available.
+	 *
+	 *     @type string $0 Image source URL.
+	 *     @type int    $1 Image width in pixels.
+	 *     @type int    $2 Image height in pixels.
+	 * }
 	 * @param int          $attachment_id Image attachment ID.
-	 * @param string|array $size          Size of image. Image size or array of width and height values
+	 * @param string|int[] $size          Requested size of image. Image size name, or array of width
-	 *                                    (in that order). Default 'thumbnail'.
+	 *                                    and height values (in that order).
-	 * @param bool         $icon          Whether the image should be treated as an icon. Default false.
+	 * @param bool         $icon          Whether the image should be treated as an icon.
 	 */
 	return apply_filters( 'wp_get_attachment_image_src', $image, $attachment_id, $size, $icon );
 }

wp-includes/post.php

@@ -6087,7 +6087,7 @@ function wp_attachment_is_image( $post = null ) {
 }
 
 /**
- * Retrieve the icon for a MIME type.
+ * Retrieve the icon for a MIME type or attachment.
  *
  * @since 2.1.0
  *

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.4-beta3-47393';
+$wp_version = '5.4-beta3-47394';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.