Docs: Improve documentation for get_avatar() and related functions.

Includes:
* Expanding and synchronizing documentation for the `default` and `rating` arguments.
* Adding `@since` entries for the `loading`, `fetchpriority`, and `decoding` arguments.
* Wrapping long lines as per the documentation standards.
* Fixing a typo in the `identicon` value.
* Minor formatting edits for consistency.

Follow-up to [31107], [45632], [47554], [53480], [56037].

See #58833.

git-svn-id: https://develop.svn.wordpress.org/trunk@56767 602fd350-edb4-49c9-b593-d223f7449a82

Author: SergeyBiryukov

src/wp-includes/link-template.php

@@ -4250,27 +4250,37 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) {
 	}
 }
 
-
 /**
  * Retrieves the avatar URL.
  *
  * @since 4.2.0
  *
- * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash,
+ * @param mixed $id_or_email The avatar to retrieve a URL for. Accepts a user ID, Gravatar MD5 hash,
  *                           user email, WP_User object, WP_Post object, or WP_Comment object.
  * @param array $args {
  *     Optional. Arguments to use instead of the default arguments.
  *
  *     @type int    $size           Height and width of the avatar in pixels. Default 96.
- *     @type string $default        URL for the default image or a default type. Accepts '404' (return
- *                                  a 404 instead of a default image), 'retro' (8bit), 'RoboHash' (robohash),
- *                                  'monsterid' (monster), 'wavatar' (cartoon face), 'indenticon' (the "quilt"),
- *                                  'mystery', 'mm', or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF),
- *                                  or 'gravatar_default' (the Gravatar logo). Default is the value of the
- *                                  'avatar_default' option, with a fallback of 'mystery'.
- *     @type bool   $force_default  Whether to always show the default image, never the Gravatar. Default false.
- *     @type string $rating         What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
- *                                  judged in that order. Default is the value of the 'avatar_rating' option.
+ *     @type string $default        URL for the default image or a default type. Accepts:
+ *                                  - '404' (return a 404 instead of a default image)
+ *                                  - 'retro' (a 8-bit arcade-style pixelated face)
+ *                                  - 'robohash' (a robot)
+ *                                  - 'monsterid' (a monster)
+ *                                  - 'wavatar' (a cartoon face)
+ *                                  - 'identicon' (the "quilt", a geometric pattern)
+ *                                  - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
+ *                                  - 'blank' (transparent GIF)
+ *                                  - 'gravatar_default' (the Gravatar logo)
+ *                                  Default is the value of the 'avatar_default' option,
+ *                                  with a fallback of 'mystery'.
+ *     @type bool   $force_default  Whether to always show the default image, never the Gravatar.
+ *                                  Default false.
+ *     @type string $rating         What rating to display avatars up to. Accepts:
+ *                                  - 'G' (suitable for all audiences)
+ *                                  - 'PG' (possibly offensive, usually for audiences 13 and above)
+ *                                  - 'R' (intended for adult audiences above 17)
+ *                                  - 'X' (even more mature than above)
+ *                                  Default is the value of the 'avatar_rating' option.
  *     @type string $scheme         URL scheme to use. See set_url_scheme() for accepted values.
  *                                  Default null.
  *     @type array  $processed_args When the function returns, the value will be the processed/sanitized $args
@@ -4283,7 +4293,6 @@ function get_avatar_url( $id_or_email, $args = null ) {
 	return $args['url'];
 }
 
-
 /**
  * Check if this comment type allows avatars to be retrieved.
  *
@@ -4305,7 +4314,6 @@ function is_avatar_comment_type( $comment_type ) {
 	return in_array( $comment_type, (array) $allowed_comment_types, true );
 }
 
-
 /**
  * Retrieves default data about the avatar.
  *
@@ -4316,23 +4324,35 @@ function is_avatar_comment_type( $comment_type ) {
  * @param array $args {
  *     Optional. Arguments to use instead of the default arguments.
  *
- *     @type int    $size           Height and width of the avatar image file in pixels. Default 96.
+ *     @type int    $size           Height and width of the avatar in pixels. Default 96.
  *     @type int    $height         Display height of the avatar in pixels. Defaults to $size.
  *     @type int    $width          Display width of the avatar in pixels. Defaults to $size.
- *     @type string $default        URL for the default image or a default type. Accepts '404' (return
- *                                  a 404 instead of a default image), 'retro' (8bit), 'monsterid' (monster),
- *                                  'wavatar' (cartoon face), 'indenticon' (the "quilt"), 'mystery', 'mm',
- *                                  or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF), or
- *                                  'gravatar_default' (the Gravatar logo). Default is the value of the
- *                                  'avatar_default' option, with a fallback of 'mystery'.
- *     @type bool   $force_default  Whether to always show the default image, never the Gravatar. Default false.
- *     @type string $rating         What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
- *                                  judged in that order. Default is the value of the 'avatar_rating' option.
+ *     @type string $default        URL for the default image or a default type. Accepts:
+ *                                  - '404' (return a 404 instead of a default image)
+ *                                  - 'retro' (a 8-bit arcade-style pixelated face)
+ *                                  - 'robohash' (a robot)
+ *                                  - 'monsterid' (a monster)
+ *                                  - 'wavatar' (a cartoon face)
+ *                                  - 'identicon' (the "quilt", a geometric pattern)
+ *                                  - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
+ *                                  - 'blank' (transparent GIF)
+ *                                  - 'gravatar_default' (the Gravatar logo)
+ *                                  Default is the value of the 'avatar_default' option,
+ *                                  with a fallback of 'mystery'.
+ *     @type bool   $force_default  Whether to always show the default image, never the Gravatar.
+ *                                  Default false.
+ *     @type string $rating         What rating to display avatars up to. Accepts:
+ *                                  - 'G' (suitable for all audiences)
+ *                                  - 'PG' (possibly offensive, usually for audiences 13 and above)
+ *                                  - 'R' (intended for adult audiences above 17)
+ *                                  - 'X' (even more mature than above)
+ *                                  Default is the value of the 'avatar_rating' option.
  *     @type string $scheme         URL scheme to use. See set_url_scheme() for accepted values.
  *                                  Default null.
  *     @type array  $processed_args When the function returns, the value will be the processed/sanitized $args
  *                                  plus a "found_avatar" guess. Pass as a reference. Default null.
- *     @type string $extra_attr     HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
+ *     @type string $extra_attr     HTML attributes to insert in the IMG element. Is not sanitized.
+ *                                  Default empty.
  * }
  * @return array {
  *     Along with the arguments passed in `$args`, this will contain a couple of extra arguments.

src/wp-includes/pluggable.php

@@ -2797,26 +2797,41 @@ function wp_set_password( $password, $user_id ) {
 	 * Retrieves the avatar `<img>` tag for a user, email address, MD5 hash, comment, or post.
 	 *
 	 * @since 2.5.0
-	 * @since 4.2.0 Optional `$args` parameter added.
+	 * @since 4.2.0 Added the optional `$args` parameter.
+	 * @since 5.5.0 Added the `loading` argument.
+	 * @since 6.1.0 Added the `decoding` argument.
+	 * @since 6.3.0 Added the `fetchpriority` argument.
 	 *
-	 * @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          Optional. Height and width of the avatar image file in pixels. Default 96.
-	 * @param string $default_value URL for the default image or a default type. Accepts '404' (return
-	 *                              a 404 instead of a default image), 'retro' (8bit), 'RoboHash' (robohash),
-	 *                              'monsterid' (monster), 'wavatar' (cartoon face), 'indenticon' (the "quilt"),
-	 *                              'mystery', 'mm', or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF),
-	 *                              or 'gravatar_default' (the Gravatar logo). Default is the value of the
-	 *                              'avatar_default' option, with a fallback of 'mystery'.
-	 * @param string $alt           Optional. Alternative text to use in img tag. Default empty.
+	 * @param int    $size          Optional. Height and width of the avatar in pixels. Default 96.
+	 * @param string $default_value URL for the default image or a default type. Accepts:
+	 *                              - '404' (return a 404 instead of a default image)
+	 *                              - 'retro' (a 8-bit arcade-style pixelated face)
+	 *                              - 'robohash' (a robot)
+	 *                              - 'monsterid' (a monster)
+	 *                              - 'wavatar' (a cartoon face)
+	 *                              - 'identicon' (the "quilt", a geometric pattern)
+	 *                              - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
+	 *                              - 'blank' (transparent GIF)
+	 *                              - 'gravatar_default' (the Gravatar logo)
+	 *                              Default is the value of the 'avatar_default' option,
+	 *                              with a fallback of 'mystery'.
+	 * @param string $alt           Optional. Alternative text to use in the avatar image tag.
+	 *                              Default empty.
 	 * @param array  $args {
 	 *     Optional. Extra arguments to retrieve the avatar.
 	 *
 	 *     @type int          $height        Display height of the avatar in pixels. Defaults to $size.
 	 *     @type int          $width         Display width of the avatar in pixels. Defaults to $size.
-	 *     @type bool         $force_default Whether to always show the default image, never the Gravatar. Default false.
-	 *     @type string       $rating        What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
-	 *                                       judged in that order. Default is the value of the 'avatar_rating' option.
+	 *     @type bool         $force_default Whether to always show the default image, never the Gravatar.
+	 *                                       Default false.
+	 *     @type string       $rating        What rating to display avatars up to. Accepts:
+	 *                                       - 'G' (suitable for all audiences)
+	 *                                       - 'PG' (possibly offensive, usually for audiences 13 and above)
+	 *                                       - 'R' (intended for adult audiences above 17)
+	 *                                       - 'X' (even more mature than above)
+	 *                                       Default is the value of the 'avatar_rating' option.
 	 *     @type string       $scheme        URL scheme to use. See set_url_scheme() for accepted values.
 	 *                                       Default null.
 	 *     @type array|string $class         Array or string of additional classes to add to the img element.
@@ -2825,7 +2840,12 @@ function wp_set_password( $password, $user_id ) {
 	 *                                       Default false.
 	 *     @type string       $loading       Value for the `loading` attribute.
 	 *                                       Default null.
-	 *     @type string       $extra_attr    HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
+	 *     @type string       $fetchpriority Value for the `fetchpriority` attribute.
+	 *                                       Default null.
+	 *     @type string       $decoding      Value for the `decoding` attribute.
+	 *                                       Default null.
+	 *     @type string       $extra_attr    HTML attributes to insert in the IMG element. Is not sanitized.
+	 *                                       Default empty.
 	 * }
 	 * @return string|false `<img>` tag for the user's avatar. False on failure.
 	 */
@@ -2844,8 +2864,8 @@ function get_avatar( $id_or_email, $size = 96, $default_value = '', $alt = '', $
 			'force_display' => false,
 			'loading'       => null,
 			'fetchpriority' => null,
-			'extra_attr'    => '',
 			'decoding'      => null,
+			'extra_attr'    => '',
 		);
 
 		if ( empty( $args ) ) {
@@ -2883,7 +2903,7 @@ function get_avatar( $id_or_email, $size = 96, $default_value = '', $alt = '', $
 		 * @since 4.2.0
 		 *
 		 * @param string|null $avatar      HTML for the user's avatar. Default null.
-		 * @param mixed       $id_or_email The avatar 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.
 		 */
@@ -2922,7 +2942,7 @@ function get_avatar( $id_or_email, $size = 96, $default_value = '', $alt = '', $
 			}
 		}
 
-		// Add `loading`, `fetchpriority` and `decoding` attributes.
+		// Add `loading`, `fetchpriority`, and `decoding` attributes.
 		$extra_attr = $args['extra_attr'];
 
 		if ( in_array( $args['loading'], array( 'lazy', 'eager' ), true )
@@ -2935,25 +2955,24 @@ function get_avatar( $id_or_email, $size = 96, $default_value = '', $alt = '', $
 			$extra_attr .= "loading='{$args['loading']}'";
 		}
 
-		if ( in_array( $args['decoding'], array( 'async', 'sync', 'auto' ), true )
-			&& ! preg_match( '/\bdecoding\s*=/', $extra_attr )
+		if ( in_array( $args['fetchpriority'], array( 'high', 'low', 'auto' ), true )
+			&& ! preg_match( '/\bfetchpriority\s*=/', $extra_attr )
 		) {
 			if ( ! empty( $extra_attr ) ) {
 				$extra_attr .= ' ';
 			}
 
-			$extra_attr .= "decoding='{$args['decoding']}'";
+			$extra_attr .= "fetchpriority='{$args['fetchpriority']}'";
 		}
 
-		// Add support for `fetchpriority`.
-		if ( in_array( $args['fetchpriority'], array( 'high', 'low', 'auto' ), true )
-			&& ! preg_match( '/\bfetchpriority\s*=/', $extra_attr )
+		if ( in_array( $args['decoding'], array( 'async', 'sync', 'auto' ), true )
+			&& ! preg_match( '/\bdecoding\s*=/', $extra_attr )
 		) {
 			if ( ! empty( $extra_attr ) ) {
 				$extra_attr .= ' ';
 			}
 
-			$extra_attr .= "fetchpriority='{$args['fetchpriority']}'";
+			$extra_attr .= "decoding='{$args['decoding']}'";
 		}
 
 		$avatar = sprintf(
@@ -2971,14 +2990,22 @@ function get_avatar( $id_or_email, $size = 96, $default_value = '', $alt = '', $
 		 * Filters the HTML for a user's avatar.
 		 *
 		 * @since 2.5.0
-		 * @since 4.2.0 The `$args` parameter was added.
+		 * @since 4.2.0 Added the `$args` parameter.
 		 *
 		 * @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,
+		 * @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_value URL for the default image or a default type. Accepts '404', 'retro', 'monsterid',
-		 *                              'wavatar', 'indenticon', 'mystery', 'mm', 'mysteryman', 'blank', or 'gravatar_default'.
+		 * @param int    $size          Height and width of the avatar in pixels.
+		 * @param string $default_value URL for the default image or a default type. Accepts:
+		 *                              - '404' (return a 404 instead of a default image)
+		 *                              - 'retro' (a 8-bit arcade-style pixelated face)
+		 *                              - 'robohash' (a robot)
+		 *                              - 'monsterid' (a monster)
+		 *                              - 'wavatar' (a cartoon face)
+		 *                              - 'identicon' (the "quilt", a geometric pattern)
+		 *                              - 'mystery', 'mm', or 'mysteryman' (The Oyster Man)
+		 *                              - 'blank' (transparent GIF)
+		 *                              - 'gravatar_default' (the Gravatar logo)
 		 * @param string $alt           Alternative text to use in the avatar image tag.
 		 * @param array  $args          Arguments passed to get_avatar_data(), after processing.
 		 */

src/wp-includes/rest-api.php

@@ -1215,13 +1215,13 @@ function rest_add_application_passwords_to_index( $response ) {
 }
 
 /**
- * Retrieves the avatar urls in various sizes.
+ * Retrieves the avatar URLs in various sizes.
  *
  * @since 4.7.0
  *
  * @see get_avatar_url()
  *
- * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash,
+ * @param mixed $id_or_email The avatar to retrieve a URL for. Accepts a user ID, Gravatar MD5 hash,
  *                           user email, WP_User object, WP_Post object, or WP_Comment object.
  * @return (string|false)[] Avatar URLs keyed by size. Each value can be a URL string or boolean false.
  */