From 62260b9fbf916e4f287a2e45d9847ecb51e67e46 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Mon, 24 Aug 2020 22:02:44 +0000
Subject: [PATCH] Docs: Add documentation and a `@since` note about the
 `loading` attribute added to `wp_get_attachment_image()`.

Follow-up to [48272].

Props audrasjb.
Fixes #51122.

git-svn-id: https://develop.svn.wordpress.org/trunk@48852 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/media.php | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
index 1871678fad..0128c9d2d7 100644
--- a/src/wp-includes/media.php
+++ b/src/wp-includes/media.php
@@ -1002,6 +1002,7 @@ function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon
  * browser scale down the image.
  *
  * @since 2.5.0
+ * @since 5.5.0 The `$loading` attribute was added.
  *
  * @param int          $attachment_id Image attachment ID.
  * @param string|array $size          Optional. Image size. Accepts any valid image size, or an array of width
@@ -1010,13 +1011,16 @@ function wp_get_attachment_image_src( $attachment_id, $size = 'thumbnail', $icon
  * @param string|array $attr {
  *     Optional. Attributes for the image markup.
  *
- *     @type string $src    Image attachment URL.
- *     @type string $class  CSS class name or space-separated list of classes.
- *                          Default `attachment-$size_class size-$size_class`,
- *                          where `$size_class` is the image size being requested.
- *     @type string $alt    Image description for the alt attribute.
- *     @type string $srcset The 'srcset' attribute value.
- *     @type string $sizes  The 'sizes' attribute value.
+ *     @type string       $src     Image attachment URL.
+ *     @type string       $class   CSS class name or space-separated list of classes.
+ *                                 Default `attachment-$size_class size-$size_class`,
+ *                                 where `$size_class` is the image size being requested.
+ *     @type string       $alt     Image description for the alt attribute.
+ *     @type string       $srcset  The 'srcset' attribute value.
+ *     @type string       $sizes   The 'sizes' attribute value.
+ *     @type string|false $loading The 'loading' attribute value. Passing a value of false
+ *                                 will result in the attribute being omitted for the image.
+ *                                 Defaults to 'lazy', depending on wp_lazy_loading_enabled().
  * }
  * @return string HTML img element or empty string on failure.
  */
@@ -1048,8 +1052,8 @@ function wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = f
 
 		$attr = wp_parse_args( $attr, $default_attr );
 
-		// If `loading` attribute default of `lazy` is overridden for this
-		// image to omit the attribute, ensure it is not included.
+		// If the default value of `lazy` for the `loading` attribute is overridden
+		// to omit the attribute for this image, ensure it is not included.
 		if ( array_key_exists( 'loading', $attr ) && ! $attr['loading'] ) {
 			unset( $attr['loading'] );
 		}