Docs: Miscellaneous inline documentation improvements.

See #53399

Built from https://develop.svn.wordpress.org/trunk@52422


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

wp-admin/includes/plugin-install.php

@@ -136,7 +136,7 @@ function plugins_api( $action, $args = array() ) {
 	/**
 	 * Filters the response for the current WordPress.org Plugin Installation API request.
 	 *
-	 * Passing a non-false value will effectively short-circuit the WordPress.org API request.
+	 * Returning a non-false value will effectively short-circuit the WordPress.org API request.
 	 *
 	 * If `$action` is 'query_plugins' or 'plugin_information', an object MUST be passed.
 	 * If `$action` is 'hot_tags' or 'hot_categories', an array should be passed.

wp-admin/includes/theme.php

@@ -521,7 +521,7 @@ function themes_api( $action, $args = array() ) {
 	/**
 	 * Filters whether to override the WordPress.org Themes API.
 	 *
-	 * Passing a non-false value will effectively short-circuit the WordPress.org API request.
+	 * Returning a non-false value will effectively short-circuit the WordPress.org API request.
 	 *
 	 * If `$action` is 'query_themes', 'theme_information', or 'feature_list', an object MUST
 	 * be passed. If `$action` is 'hot_tags', an array should be passed.

wp-admin/options-reading.php

@@ -191,6 +191,7 @@ else :
 	 *
 	 * By default the privacy options form displays a single checkbox to 'discourage' search
 	 * engines from indexing the site. Hooking to this action serves a dual purpose:
+	 *
 	 * 1. Disable the single checkbox in favor of a multiple-choice list of radio buttons.
 	 * 2. Open the door to adding additional radio button choices to the list.
 	 *

wp-includes/class-wp-http.php

@@ -435,7 +435,7 @@ class WP_Http {
 		}
 
 		/**
-		 * Filters the HTTP API response immediately before the response is returned.
+		 * Filters a successful HTTP API response immediately before the response is returned.
 		 *
 		 * @since 2.9.0
 		 *

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

@@ -9,7 +9,7 @@
 /**
  * List utility.
  *
- * Utility class to handle operations on an array of objects.
+ * Utility class to handle operations on an array of objects or arrays.
  *
  * @since 4.7.0
  */
@@ -140,15 +140,15 @@ class WP_List_Util {
 	}
 
 	/**
-	 * Plucks a certain field out of each object in the list.
+	 * Plucks a certain field out of each element in the input array.
 	 *
 	 * This has the same functionality and prototype of
 	 * array_column() (PHP 5.5) but also supports objects.
 	 *
 	 * @since 4.7.0
 	 *
-	 * @param int|string $field     Field from the object to place instead of the entire object
-	 * @param int|string $index_key Optional. Field from the object to use as keys for the new array.
+	 * @param int|string $field     Field to fetch from the object or array.
+	 * @param int|string $index_key Optional. Field from the element to use as keys for the new array.
 	 *                              Default null.
 	 * @return array Array of found values. If `$index_key` is set, an array of found values with keys
 	 *               corresponding to `$index_key`. If `$index_key` is null, array keys from the original
@@ -201,7 +201,7 @@ class WP_List_Util {
 	}
 
 	/**
-	 * Sorts the list, based on one or more orderby arguments.
+	 * Sorts the input array based on one or more orderby arguments.
 	 *
 	 * @since 4.7.0
 	 *
@@ -239,7 +239,7 @@ class WP_List_Util {
 	}
 
 	/**
-	 * Callback to sort the list by specific fields.
+	 * Callback to sort an array by specific fields.
 	 *
 	 * @since 4.7.0
 	 *

wp-includes/class-wp-xmlrpc-server.php

@@ -6399,7 +6399,7 @@ class wp_xmlrpc_server extends IXR_Server {
 		/**
 		 * Filters whether to preempt the XML-RPC media upload.
 		 *
-		 * Passing a truthy value will effectively short-circuit the media upload,
+		 * Returning a truthy value will effectively short-circuit the media upload,
 		 * returning that value as a 500 error instead.
 		 *
 		 * @since 2.1.0

wp-includes/functions.php

@@ -5106,7 +5106,7 @@ function wp_list_filter( $list, $args = array(), $operator = 'AND' ) {
 }
 
 /**
- * Pluck a certain field out of each object in a list.
+ * Plucks a certain field out of each object or array in an array.
  *
  * This has the same functionality and prototype of
  * array_column() (PHP 5.5) but also supports objects.
@@ -5130,7 +5130,7 @@ function wp_list_pluck( $list, $field, $index_key = null ) {
 }
 
 /**
- * Sorts a list of objects, based on one or more orderby arguments.
+ * Sorts an array of objects or arrays based on one or more orderby arguments.
  *
  * @since 4.7.0
  *

wp-includes/pluggable.php

@@ -2720,7 +2720,7 @@ if ( ! function_exists( 'get_avatar' ) ) :
 		/**
 		 * Allows the HTML for a user's avatar to be returned early.
 		 *
-		 * Passing a non-null value will effectively short-circuit get_avatar(), passing
+		 * Returning a non-null value will effectively short-circuit get_avatar(), passing
 		 * the value through the {@see 'get_avatar'} filter and returning early.
 		 *
 		 * @since 4.2.0

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

@@ -75,7 +75,7 @@ class WP_Sitemaps_Posts extends WP_Sitemaps_Provider {
 		/**
 		 * Filters the posts URL list before it is generated.
 		 *
-		 * Passing a non-null value will effectively short-circuit the generation,
+		 * Returning a non-null value will effectively short-circuit the generation,
 		 * returning that value instead.
 		 *
 		 * @since 5.5.0

wp-includes/sitemaps/providers/class-wp-sitemaps-taxonomies.php

@@ -71,7 +71,7 @@ class WP_Sitemaps_Taxonomies extends WP_Sitemaps_Provider {
 		/**
 		 * Filters the taxonomies URL list before it is generated.
 		 *
-		 * Passing a non-null value will effectively short-circuit the generation,
+		 * Returning a non-null value will effectively short-circuit the generation,
 		 * returning that value instead.
 		 *
 		 * @since 5.5.0

wp-includes/sitemaps/providers/class-wp-sitemaps-users.php

@@ -40,7 +40,7 @@ class WP_Sitemaps_Users extends WP_Sitemaps_Provider {
 		/**
 		 * Filters the users URL list before it is generated.
 		 *
-		 * Passing a non-null value will effectively short-circuit the generation,
+		 * Returning a non-null value will effectively short-circuit the generation,
 		 * returning that value instead.
 		 *
 		 * @since 5.5.0
@@ -101,7 +101,7 @@ class WP_Sitemaps_Users extends WP_Sitemaps_Provider {
 		/**
 		 * Filters the max number of pages for a user sitemap before it is generated.
 		 *
-		 * Passing a non-null value will effectively short-circuit the generation,
+		 * Returning a non-null value will effectively short-circuit the generation,
 		 * returning that value instead.
 		 *
 		 * @since 5.5.0

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-beta4-52421';
+$wp_version = '5.9-beta4-52422';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/wp-db.php

@@ -2876,7 +2876,7 @@ class wpdb {
 		/**
 		 * Filters the table charset value before the DB is checked.
 		 *
-		 * Passing a non-null value to the filter will effectively short-circuit
+		 * Returning a non-null value from the filter will effectively short-circuit
 		 * checking the DB for the charset, returning that value instead.
 		 *
 		 * @since 4.2.0