Docs: Update various DocBlocks and inline comments per the documentat…

…ion standards.

Includes minor formatting edits for consistency.

Follow-up to [53/tests], [12179], [12946], [35288], [37884], [38810], [38928], [46596], [48131], [52955], [53548], [53813], [53873], [54118], [54316], [54420], [54421], [54803].

See #56792.

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

src/js/_enqueues/lib/nav-menu.js

@@ -1557,14 +1557,14 @@
 		});
 	});
 
-	// Show bulk action
+	// Show bulk action.
 	$( document ).on( 'menu-item-added', function() {
 		if ( ! $( '.bulk-actions' ).is( ':visible' ) ) {
 			$( '.bulk-actions' ).show();
 		}
 	} );
 
-	// Hide bulk action
+	// Hide bulk action.
 	$( document ).on( 'menu-removing-item', function( e, el ) {
 		var menuElement = $( el ).parents( '#menu-to-edit' );
 		if ( menuElement.find( 'li' ).length === 1 && $( '.bulk-actions' ).is( ':visible' ) ) {

src/wp-includes/class-wp-list-util.php

@@ -207,9 +207,10 @@ public function pluck( $field, $index_key = null ) {
 	 * @since 4.7.0
 	 *
 	 * @param string|array $orderby       Optional. Either the field name to order by or an array
-	 *                                    of multiple orderby fields as $orderby => $order.
-	 * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby
-	 *                                    is a string.
+	 *                                    of multiple orderby fields as `$orderby => $order`.
+	 *                                    Default empty array.
+	 * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
+	 *                                    is a string. Default 'ASC'.
 	 * @param bool         $preserve_keys Optional. Whether to preserve keys. Default false.
 	 * @return array The sorted array.
 	 */

src/wp-includes/compat.php

@@ -156,7 +156,7 @@ function mb_strlen( $string, $encoding = null ) {
 /**
  * Internal compat function to mimic mb_strlen().
  *
- * Only understands UTF-8 and 8bit.  All other character sets will be treated as 8bit.
+ * Only understands UTF-8 and 8bit. All other character sets will be treated as 8bit.
  * For `$encoding === UTF-8`, the `$str` input is expected to be a valid UTF-8 byte
  * sequence. The behavior of this function for invalid inputs is undefined.
  *

src/wp-includes/functions.php

@@ -934,7 +934,7 @@ function do_enclose( $content, $post ) {
 	 * @since 4.4.0
 	 *
 	 * @param string[] $post_links An array of enclosure links.
-	 * @param int      $post_ID    Post ID.
+	 * @param int      $post_id    Post ID.
 	 */
 	$post_links = apply_filters( 'enclosure_links', $post_links, $post->ID );
 
@@ -3330,7 +3330,7 @@ function wp_get_mime_types() {
 	 * @since 3.5.0
 	 *
 	 * @param string[] $wp_get_mime_types Mime types keyed by the file extension regex
-	 *                                 corresponding to those types.
+	 *                                    corresponding to those types.
 	 */
 	return apply_filters(
 		'mime_types',
@@ -5200,9 +5200,10 @@ function wp_list_pluck( $list, $field, $index_key = null ) {
  *
  * @param array        $list          An array of objects or arrays to sort.
  * @param string|array $orderby       Optional. Either the field name to order by or an array
- *                                    of multiple orderby fields as $orderby => $order.
- * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby
- *                                    is a string.
+ *                                    of multiple orderby fields as `$orderby => $order`.
+ *                                    Default empty array.
+ * @param string       $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
+ *                                    is a string. Default 'ASC'.
  * @param bool         $preserve_keys Optional. Whether to preserve keys. Default false.
  * @return array The sorted array.
  */

src/wp-includes/l10n.php

@@ -176,7 +176,7 @@ function determine_locale() {
  * *Note:* Don't use translate() directly, use __() or related functions.
  *
  * @since 2.2.0
- * @since 5.5.0 Introduced gettext-{$domain} filter.
+ * @since 5.5.0 Introduced `gettext-{$domain}` filter.
  *
  * @param string $text   Text to translate.
  * @param string $domain Optional. Text domain. Unique identifier for retrieving translated strings.
@@ -242,7 +242,7 @@ function before_last_bar( $string ) {
  * *Note:* Don't use translate_with_gettext_context() directly, use _x() or related functions.
  *
  * @since 2.8.0
- * @since 5.5.0 Introduced gettext_with_context-{$domain} filter.
+ * @since 5.5.0 Introduced `gettext_with_context-{$domain}` filter.
  *
  * @param string $text    Text to translate.
  * @param string $context Context information for the translators.
@@ -463,7 +463,7 @@ function esc_html_x( $text, $context, $domain = 'default' ) {
  *     printf( _n( '%s person', '%s people', $count, 'text-domain' ), number_format_i18n( $count ) );
  *
  * @since 2.8.0
- * @since 5.5.0 Introduced ngettext-{$domain} filter.
+ * @since 5.5.0 Introduced `ngettext-{$domain}` filter.
  *
  * @param string $single The text to be used if the number is singular.
  * @param string $plural The text to be used if the number is plural.
@@ -521,7 +521,7 @@ function _n( $single, $plural, $number, $domain = 'default' ) {
  *     printf( _nx( '%s group', '%s groups', $animals, 'group of animals', 'text-domain' ), number_format_i18n( $animals ) );
  *
  * @since 2.8.0
- * @since 5.5.0 Introduced ngettext_with_context-{$domain} filter.
+ * @since 5.5.0 Introduced `ngettext_with_context-{$domain}` filter.
  *
  * @param string $single  The text to be used if the number is singular.
  * @param string $plural  The text to be used if the number is plural.
@@ -1022,9 +1022,9 @@ function load_theme_textdomain( $domain, $path = false ) {
 }
 
 /**
- * Loads the child themes translated strings.
+ * Loads the child theme's translated strings.
  *
- * If the current locale exists as a .mo file in the child themes
+ * If the current locale exists as a .mo file in the child theme's
  * root directory, it will be included in the translated strings by the $domain.
  *
  * The .mo files must be named based on the locale exactly.
@@ -1361,7 +1361,8 @@ function translate_user_role( $name, $domain = 'default' ) {
  *
  * @param string $dir A directory to search for language files.
  *                    Default WP_LANG_DIR.
- * @return string[] An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
+ * @return string[] An array of language codes or an empty array if no languages are present.
+ *                  Language codes are formed by stripping the .mo extension from the language file names.
  */
 function get_available_languages( $dir = null ) {
 	$languages = array();

src/wp-includes/load.php

@@ -1322,10 +1322,10 @@ function get_current_network_id() {
  * @access private
  *
  * @global WP_Textdomain_Registry $wp_textdomain_registry WordPress Textdomain Registry.
- * @global WP_Locale $wp_locale WordPress date and time locale object.
+ * @global WP_Locale              $wp_locale              WordPress date and time locale object.
  */
 function wp_load_translations_early() {
-	global $wp_locale, $wp_textdomain_registry;
+	global $wp_textdomain_registry, $wp_locale;
 
 	static $loaded = false;
 	if ( $loaded ) {

src/wp-includes/post.php

@@ -1547,9 +1547,8 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
  *
  * @global array $wp_post_types List of post types.
  *
- * @param string       $post_type Post type key. Must not exceed 20 characters and may
- *                                only contain lowercase alphanumeric characters, dashes,
- *                                and underscores. See sanitize_key().
+ * @param string       $post_type Post type key. Must not exceed 20 characters and may only contain
+ *                                lowercase alphanumeric characters, dashes, and underscores. See sanitize_key().
  * @param array|string $args {
  *     Array or string of arguments for registering a post type.
  *
@@ -4198,7 +4197,7 @@ function wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true )
 
 		if ( $update && strtolower( urlencode( $post_name ) ) == $check_name && get_post_field( 'post_name', $post_ID ) == $check_name ) {
 			$post_name = $check_name;
-		} else { // new post, or slug has changed.
+		} else { // New post, or slug has changed.
 			$post_name = sanitize_title( $post_name );
 		}
 	}

src/wp-includes/rest-api/class-wp-rest-server.php

@@ -553,7 +553,7 @@ public function serve_request( $path = null ) {
 	 * Converts a response to data to send.
 	 *
 	 * @since 4.4.0
-	 * @since 5.4.0 The $embed parameter can now contain a list of link relations to include.
+	 * @since 5.4.0 The `$embed` parameter can now contain a list of link relations to include.
 	 *
 	 * @param WP_REST_Response $response Response object.
 	 * @param bool|string[]    $embed    Whether to embed all links, a filtered list of link relations, or no links.
@@ -677,7 +677,7 @@ public static function get_compact_response_links( $response ) {
 	 * Embeds the links from the data into the request.
 	 *
 	 * @since 4.4.0
-	 * @since 5.4.0 The $embed parameter can now contain a list of link relations to include.
+	 * @since 5.4.0 The `$embed` parameter can now contain a list of link relations to include.
 	 *
 	 * @param array         $data  Data from the request.
 	 * @param bool|string[] $embed Whether to embed all links or a filtered list of link relations.
@@ -759,7 +759,7 @@ protected function embed_links( $data, $embed = true ) {
 	 * data instead.
 	 *
 	 * @since 4.4.0
-	 * @since 6.0.0 The $embed parameter can now contain a list of link relations to include
+	 * @since 6.0.0 The `$embed` parameter can now contain a list of link relations to include.
 	 *
 	 * @param WP_REST_Response $response Response object.
 	 * @param bool|string[]    $embed    Whether to embed all links, a filtered list of link relations, or no links.

src/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

@@ -659,11 +659,9 @@ public function create_item( $request ) {
 			&& in_array( $prepared_post->post_status, array( 'draft', 'pending' ), true )
 		) {
 			/*
-			 * `wp_unique_post_slug()` returns the same
-			 * slug for 'draft' or 'pending' posts.
+			 * `wp_unique_post_slug()` returns the same slug for 'draft' or 'pending' posts.
 			 *
-			 * To ensure that a unique slug is generated,
-			 * pass the post data with the 'publish' status.
+			 * To ensure that a unique slug is generated, pass the post data with the 'publish' status.
 			 */
 			$prepared_post->post_name = wp_unique_post_slug(
 				$prepared_post->post_name,
@@ -862,15 +860,19 @@ public function update_item( $request ) {
 		}
 
 		/*
-		 * `wp_unique_post_slug()` returns the same
-		 * slug for 'draft' or 'pending' posts.
+		 * `wp_unique_post_slug()` returns the same slug for 'draft' or 'pending' posts.
 		 *
-		 * To ensure that a unique slug is generated,
-		 * pass the post data with the 'publish' status.
+		 * To ensure that a unique slug is generated, pass the post data with the 'publish' status.
 		 */
 		if ( ! empty( $post->post_name ) && in_array( $post_status, array( 'draft', 'pending' ), true ) ) {
 			$post_parent     = ! empty( $post->post_parent ) ? $post->post_parent : 0;
-			$post->post_name = wp_unique_post_slug( $post->post_name, $post->ID, 'publish', $post->post_type, $post_parent );
+			$post->post_name = wp_unique_post_slug(
+				$post->post_name,
+				$post->ID,
+				'publish',
+				$post->post_type,
+				$post_parent
+			);
 		}
 
 		// Convert the post object to an array, otherwise wp_update_post() will expect non-escaped input.

src/wp-includes/sitemaps/providers/class-wp-sitemaps-posts.php

@@ -221,7 +221,7 @@ protected function get_posts_query_args( $post_type ) {
 				'no_found_rows'          => true,
 				'update_post_term_cache' => false,
 				'update_post_meta_cache' => false,
-				'ignore_sticky_posts'    => true, // sticky posts will still appear, but they won't be moved to the front.
+				'ignore_sticky_posts'    => true, // Sticky posts will still appear, but they won't be moved to the front.
 			),
 			$post_type
 		);

src/wp-includes/taxonomy.php

@@ -390,8 +390,8 @@ function is_taxonomy_hierarchical( $taxonomy ) {
  *
  * @global WP_Taxonomy[] $wp_taxonomies Registered taxonomies.
  *
- * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters and may only contain lowercase alphanumeric
- *                                  characters, dashes, and underscores. See sanitize_key().
+ * @param string       $taxonomy    Taxonomy key. Must not exceed 32 characters and may only contain
+ *                                  lowercase alphanumeric characters, dashes, and underscores. See sanitize_key().
  * @param array|string $object_type Object type or array of object types with which the taxonomy should be associated.
  * @param array|string $args        {
  *     Optional. Array or query string of arguments for registering a taxonomy.

src/wp-includes/theme.php

@@ -3567,7 +3567,7 @@ function _wp_customize_publish_changeset( $new_status, $old_status, $changeset_p
 		remove_action( 'customize_register', array( $wp_customize, 'register_controls' ) );
 		$wp_customize->register_controls();
 
-		/** This filter is documented in /wp-includes/class-wp-customize-manager.php */
+		/** This filter is documented in wp-includes/class-wp-customize-manager.php */
 		do_action( 'customize_register', $wp_customize );
 	}
 	$wp_customize->_publish_changeset_values( $changeset_post->ID );

tests/phpunit/includes/utils.php

@@ -459,12 +459,12 @@ function gen_tests_array( $name, $array ) {
 }
 
 /**
- * Use to create objects by yourself
+ * Use to create objects by yourself.
  */
 class MockClass extends stdClass {}
 
 /**
- * Drops all tables from the WordPress database
+ * Drops all tables from the WordPress database.
  */
 function drop_tables() {
 	global $wpdb;

tests/phpunit/tests/functions/sizeFormat.php

@@ -14,58 +14,58 @@ class Tests_Functions_SizeFormat extends WP_UnitTestCase {
 
 	public function _data_size_format() {
 		return array(
-			// Invalid values
+			// Invalid values.
 			array( array(), 0, false ),
 			array( 'baba', 0, false ),
 			array( '', 0, false ),
 			array( '-1', 0, false ),
 			array( -1, 0, false ),
-			// Bytes
+			// Bytes.
 			array( 0, 0, '0 B' ),
 			array( 1, 0, '1 B' ),
 			array( 1023, 0, '1,023 B' ),
-			// Kilobytes
+			// Kilobytes.
 			array( KB_IN_BYTES, 0, '1 KB' ),
 			array( KB_IN_BYTES, 2, '1.00 KB' ),
 			array( 2.5 * KB_IN_BYTES, 0, '3 KB' ),
 			array( 2.5 * KB_IN_BYTES, 2, '2.50 KB' ),
 			array( 10 * KB_IN_BYTES, 0, '10 KB' ),
-			// Megabytes
+			// Megabytes.
 			array( (string) 1024 * KB_IN_BYTES, 2, '1.00 MB' ),
 			array( MB_IN_BYTES, 0, '1 MB' ),
 			array( 2.5 * MB_IN_BYTES, 0, '3 MB' ),
 			array( 2.5 * MB_IN_BYTES, 2, '2.50 MB' ),
-			// Gigabytes
+			// Gigabytes.
 			array( (string) 1024 * MB_IN_BYTES, 2, '1.00 GB' ),
 			array( GB_IN_BYTES, 0, '1 GB' ),
 			array( 2.5 * GB_IN_BYTES, 0, '3 GB' ),
 			array( 2.5 * GB_IN_BYTES, 2, '2.50 GB' ),
-			// Terabytes
+			// Terabytes.
 			array( (string) 1024 * GB_IN_BYTES, 2, '1.00 TB' ),
 			array( TB_IN_BYTES, 0, '1 TB' ),
 			array( 2.5 * TB_IN_BYTES, 0, '3 TB' ),
 			array( 2.5 * TB_IN_BYTES, 2, '2.50 TB' ),
-			// Petabytes
+			// Petabytes.
 			array( (string) 1024 * TB_IN_BYTES, 2, '1.00 PB' ),
 			array( PB_IN_BYTES, 0, '1 PB' ),
 			array( 2.5 * PB_IN_BYTES, 0, '3 PB' ),
 			array( 2.5 * PB_IN_BYTES, 2, '2.50 PB' ),
-			// Exabytes
+			// Exabytes.
 			array( (string) 1024 * PB_IN_BYTES, 2, '1.00 EB' ),
 			array( EB_IN_BYTES, 0, '1 EB' ),
 			array( 2.5 * EB_IN_BYTES, 0, '3 EB' ),
 			array( 2.5 * EB_IN_BYTES, 2, '2.50 EB' ),
-			// Zettabytes
+			// Zettabytes.
 			array( (string) 1024 * EB_IN_BYTES, 2, '1.00 ZB' ),
 			array( ZB_IN_BYTES, 0, '1 ZB' ),
 			array( 2.5 * ZB_IN_BYTES, 0, '3 ZB' ),
 			array( 2.5 * ZB_IN_BYTES, 2, '2.50 ZB' ),
-			// Yottabytes
+			// Yottabytes.
 			array( (string) 1024 * ZB_IN_BYTES, 2, '1.00 YB' ),
 			array( YB_IN_BYTES, 0, '1 YB' ),
 			array( 2.5 * YB_IN_BYTES, 0, '3 YB' ),
 			array( 2.5 * YB_IN_BYTES, 2, '2.50 YB' ),
-			// Edge values
+			// Edge values.
 			array( TB_IN_BYTES + ( TB_IN_BYTES / 2 ) + MB_IN_BYTES, 1, '1.5 TB' ),
 			array( TB_IN_BYTES - MB_IN_BYTES - KB_IN_BYTES, 3, '1,023.999 GB' ),
 		);

tests/phpunit/tests/functions/wpListSort.php

@@ -12,7 +12,7 @@ class Tests_Functions_wpListSort extends WP_UnitTestCase {
 	 * @dataProvider data_test_wp_list_sort
 	 *
 	 * @param string|array $orderby Either the field name to order by or an array
-	 *                              of multiple orderby fields as $orderby => $order.
+	 *                              of multiple orderby fields as `$orderby => $order`.
 	 * @param string       $order   Either 'ASC' or 'DESC'.
 	 */
 	public function test_wp_list_sort( $list, $orderby, $order, $expected ) {
@@ -337,7 +337,7 @@ public function data_test_wp_list_sort() {
 	 * @dataProvider data_test_wp_list_sort_preserve_keys
 	 *
 	 * @param string|array $orderby Either the field name to order by or an array
-	 *                              of multiple orderby fields as $orderby => $order.
+	 *                              of multiple orderby fields as `$orderby => $order`.
 	 * @param string       $order   Either 'ASC' or 'DESC'.
 	 */
 	public function test_wp_list_sort_preserve_keys( $list, $orderby, $order, $expected ) {

tests/phpunit/tests/functions/wpListUtil.php

@@ -64,7 +64,8 @@ public function test_wp_list_util_get_output() {
 	 * @param array  $target_array The array to create the list from.
 	 * @param string $target_key   The key to pluck.
 	 * @param array  $expected     The expected array.
-	 * @param string $index_key    Optional. Field from the element to use as keys for the new array. Default null.
+	 * @param string $index_key    Optional. Field from the element to use as keys for the new array.
+	 *                             Default null.
 	 */
 	public function test_wp_list_util_pluck( $target_array, $target_key, $expected, $index_key = null ) {
 		$util   = new WP_List_Util( $target_array );
@@ -156,9 +157,11 @@ public function test_wp_list_util_sort_simple() {
 	 *
 	 * @param array  $expected      The expected array.
 	 * @param array  $target_array  The array to create a list from.
-	 * @param array  $orderby       Optional. Either the field name to order by or an array of multiple orderby fields as $orderby => $order.
+	 * @param array  $orderby       Optional. Either the field name to order by or an array
+	 *                              of multiple orderby fields as `$orderby => $order`.
 	 *                              Default empty array.
-	 * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby is a string. Default 'ASC'.
+	 * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
+	 *                              is a string. Default 'ASC'.
 	 * @param bool   $preserve_keys Optional. Whether to preserve keys. Default false.
 	 */
 	public function test_wp_list_util_sort( $expected, $target_array, $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
@@ -955,9 +958,11 @@ public function data_wp_list_util_sort_object_arrays() {
 	 *
 	 * @param array  $expected      The expected array.
 	 * @param array  $target_array  The array to create a list from.
-	 * @param array  $orderby       Optional. Either the field name to order by or an array of multiple orderby fields as $orderby => $order.
+	 * @param array  $orderby       Optional. Either the field name to order by or an array
+	 *                              of multiple orderby fields as `$orderby => $order`.
 	 *                              Default empty array.
-	 * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if $orderby is a string. Default 'ASC'.
+	 * @param string $order         Optional. Either 'ASC' or 'DESC'. Only used if `$orderby`
+	 *                              is a string. Default 'ASC'.
 	 * @param bool   $preserve_keys Optional. Whether to preserve keys. Default false.
 	 */
 	public function test_wp_list_util_sort_php_7_or_greater( $expected, $target_array, $orderby = array(), $order = 'ASC', $preserve_keys = false ) {