Docs: Various corrections and improvements to inline documentation.

johnbillion · johnbillion · commit c47f438376fd · 2022-08-04T14:50:27.000Z
See #55646 git-svn-id: https://develop.svn.wordpress.org/trunk@53827 602fd350-edb4-49c9-b593-d223f7449a82
diff --git a/src/wp-admin/authorize-application.php b/src/wp-admin/authorize-application.php
@@ -250,8 +250,8 @@
 				 *     The array of request data. All arguments are optional and may be empty.
 				 *
 				 *     @type string $app_name    The suggested name of the application.
-				 *     @type string $success_url The url the user will be redirected to after approving the application.
-				 *     @type string $reject_url  The url the user will be redirected to after rejecting the application.
+				 *     @type string $success_url The URL the user will be redirected to after approving the application.
+				 *     @type string $reject_url  The URL the user will be redirected to after rejecting the application.
 				 * }
 				 * @param WP_User $user The user authorizing the application.
 				 */
diff --git a/src/wp-admin/edit-tags.php b/src/wp-admin/edit-tags.php
@@ -486,7 +486,7 @@
 		 * @param array  $dropdown_args {
 		 *     An array of taxonomy parent drop-down arguments.
 		 *
-		 *     @type int|bool $hide_empty       Whether to hide terms not attached to any posts. Default 0|false.
+		 *     @type int|bool $hide_empty       Whether to hide terms not attached to any posts. Default 0.
 		 *     @type bool     $hide_if_empty    Whether to hide the drop-down if no terms exist. Default false.
 		 *     @type string   $taxonomy         The taxonomy slug.
 		 *     @type string   $name             Value of the name attribute to use for the drop-down select element.
diff --git a/src/wp-includes/category.php b/src/wp-includes/category.php
@@ -269,7 +269,7 @@ function sanitize_category( $category, $context = 'display' ) {
  * @param mixed  $value   Category value to sanitize.
  * @param int    $cat_id  Category ID.
  * @param string $context What filter to use, 'raw', 'display', etc.
- * @return mixed Same type as $value after $value has been sanitized.
+ * @return mixed Value after $value has been sanitized.
  */
 function sanitize_category_field( $field, $value, $cat_id, $context ) {
 	return sanitize_term_field( $field, $value, $cat_id, 'category', $context );
diff --git a/src/wp-includes/class-wp-comment-query.php b/src/wp-includes/class-wp-comment-query.php
@@ -159,7 +159,6 @@ public function __call( $name, $arguments ) {
 	 *                                                      Default null.
 	 *     @type string          $fields                    Comment fields to return. Accepts 'ids' for comment IDs
 	 *                                                      only or empty for all fields. Default empty.
-	 *     @type int             $ID                        Currently unused.
 	 *     @type array           $include_unapproved        Array of IDs or email addresses of users whose unapproved
 	 *                                                      comments will be returned by the query regardless of
 	 *                                                      `$status`. Default empty.
@@ -223,7 +222,6 @@ public function __call( $name, $arguments ) {
 	 *                                                      Default empty.
 	 *     @type int[]           $post_author__not_in       Array of author IDs *not* to retrieve comments for.
 	 *                                                      Default empty.
-	 *     @type int             $post_ID                   Currently unused.
 	 *     @type int             $post_id                   Limit results to those affiliated with a given post ID.
 	 *                                                      Default 0.
 	 *     @type int[]           $post__in                  Array of post IDs to include affiliated comments for.
diff --git a/src/wp-includes/class-wp-http.php b/src/wp-includes/class-wp-http.php
@@ -687,8 +687,8 @@ public static function processResponse( $response ) { // phpcs:ignore WordPress.
 	 *     then a numbered array is returned as the value of that header-key.
 	 *
 	 *     @type array            $response {
-	 *          @type int    $code    The response status code. Default 0.
-	 *          @type string $message The response message. Default empty.
+	 *         @type int    $code    The response status code. Default 0.
+	 *         @type string $message The response message. Default empty.
 	 *     }
 	 *     @type array            $newheaders The processed header data as a multidimensional array.
 	 *     @type WP_Http_Cookie[] $cookies    If the original headers contain the 'Set-Cookie' key,
diff --git a/src/wp-includes/class-wp-query.php b/src/wp-includes/class-wp-query.php
@@ -665,7 +665,7 @@ public function fill_query_vars( $query_vars ) {
 	 *                                                    excludes stickies from 'post__in'. Accepts 1|true, 0|false.
 	 *                                                    Default false.
 	 *     @type int             $m                       Combination YearMonth. Accepts any four-digit year and month
-	 *                                                    numbers 1-12. Default empty.
+	 *                                                    numbers 01-12. Default empty.
 	 *     @type string|string[] $meta_key                Meta key or keys to filter by.
 	 *     @type string|string[] $meta_value              Meta value or values to filter by.
 	 *     @type string          $meta_compare            MySQL operator used for comparing the meta value.
diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
@@ -4016,7 +4016,7 @@ function wp_get_shortlink( $id = 0, $context = 'post', $allow_slugs = true ) {
 	/**
 	 * Filters whether to preempt generating a shortlink for the given post.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit
+	 * Returning a value other than false from the filter will short-circuit
 	 * the shortlink generation process, returning that value instead.
 	 *
 	 * @since 3.0.0
diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
@@ -4535,9 +4535,8 @@ function wp_enqueue_media( $args = array() ) {
 	 *
 	 * @link https://core.trac.wordpress.org/ticket/31071
 	 *
-	 * @param array|null $months An array of objects with `month` and `year`
-	 *                           properties, or `null` (or any other non-array value)
-	 *                           for default behavior.
+	 * @param stdClass[]|null $months An array of objects with `month` and `year`
+	 *                                properties, or `null` for default behavior.
 	 */
 	$months = apply_filters( 'media_library_months_with_files', null );
 	if ( ! is_array( $months ) ) {
diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php
@@ -1635,15 +1635,15 @@ function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {
 }
 
 /**
- * Retrieves a list of registered meta keys for an object type.
+ * Retrieves a list of registered metadata args for an object type, keyed by their meta keys.
  *
  * @since 4.6.0
  * @since 4.9.8 The `$object_subtype` parameter was added.
  *
  * @param string $object_type    Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
  *                               or any other object type with an associated meta table.
  * @param string $object_subtype Optional. The subtype of the object type.
- * @return string[] List of registered meta keys.
+ * @return array[] List of registered metadata args, keyed by their meta keys.
  */
 function get_registered_meta_keys( $object_type, $object_subtype = '' ) {
 	global $wp_meta_keys;
diff --git a/src/wp-includes/option.php b/src/wp-includes/option.php
@@ -114,8 +114,8 @@ function get_option( $option, $default = false ) {
 	 *
 	 * The dynamic portion of the hook name, `$option`, refers to the option name.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 1.5.0
 	 * @since 4.4.0 The `$option` parameter was added.
@@ -832,8 +832,8 @@ function get_transient( $transient ) {
 	 *
 	 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 2.8.0
 	 * @since 4.4.0 The `$transient` parameter was added
@@ -1004,6 +1004,8 @@ function set_transient( $transient, $value, $expiration = 0 ) {
 /**
  * Deletes all expired transients.
  *
+ * Note that this function won't do anything if an external object cache is in use.
+ *
  * The multi-table delete syntax is used to delete the transient record
  * from table a, and the corresponding transient_timeout record from table b.
  *
@@ -1132,9 +1134,9 @@ function get_user_setting( $name, $default = false ) {
 /**
  * Adds or updates user interface setting.
  *
- * Both $name and $value can contain only ASCII letters, numbers, hyphens, and underscores.
+ * Both `$name` and `$value` can contain only ASCII letters, numbers, hyphens, and underscores.
  *
- * This function has to be used before any output has started as it calls setcookie().
+ * This function has to be used before any output has started as it calls `setcookie()`.
  *
  * @since 2.8.0
  *
@@ -1159,7 +1161,7 @@ function set_user_setting( $name, $value ) {
  *
  * Deleting settings would reset them to the defaults.
  *
- * This function has to be used before any output has started as it calls setcookie().
+ * This function has to be used before any output has started as it calls `setcookie()`.
  *
  * @since 2.7.0
  *
@@ -1389,8 +1391,8 @@ function get_network_option( $network_id, $option, $default = false ) {
 	 *
 	 * The dynamic portion of the hook name, `$option`, refers to the option name.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 2.9.0 As 'pre_site_option_' . $key
 	 * @since 3.0.0
@@ -1420,7 +1422,7 @@ function get_network_option( $network_id, $option, $default = false ) {
 	if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {
 
 		/**
-		 * Filters a specific default network option.
+		 * Filters the value of a specific default network option.
 		 *
 		 * The dynamic portion of the hook name, `$option`, refers to the option name.
 		 *
diff --git a/src/wp-includes/pluggable.php b/src/wp-includes/pluggable.php
@@ -895,6 +895,7 @@ function wp_generate_auth_cookie( $user_id, $expiration, $scheme = 'auth', $toke
 	 * Parses a cookie into its components.
 	 *
 	 * @since 2.7.0
+	 * @since 4.0.0 The `$token` element was added to the return value.
 	 *
 	 * @param string $cookie Authentication cookie.
 	 * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php
@@ -3105,8 +3105,8 @@ function wp_unique_term_slug( $slug, $term ) {
  *
  * @param int          $term_id  The ID of the term.
  * @param string       $taxonomy The taxonomy of the term.
- * @param array|string $args {
- *     Optional. Array or string of arguments for updating a term.
+ * @param array        $args {
+ *     Optional. Array of arguments for updating a term.
  *
  *     @type string $alias_of    Slug of the term to make this term an alias of.
  *                               Default empty string. Accepts a term slug.
diff --git a/src/wp-login.php b/src/wp-login.php
@@ -348,6 +348,8 @@ function login_footer( $input_id = '' ) {
 					/**
 					 * Filters default arguments for the Languages select input on the login screen.
 					 *
+					 * The arguments get passed to the wp_dropdown_languages() function.
+					 *
 					 * @since 5.9.0
 					 *
 					 * @param array $args Arguments for the Languages select input on the login screen.

Original file line number	Diff line number	Diff line change
`@@ -486,7 +486,7 @@`
`486`	`486`	`* @param array $dropdown_args {`
`487`	`487`	`* An array of taxonomy parent drop-down arguments.`
`488`	`488`	`*`
`489`		`- * @type int\|bool $hide_empty Whether to hide terms not attached to any posts. Default 0\|false.`
	`489`	`+ * @type int\|bool $hide_empty Whether to hide terms not attached to any posts. Default 0.`
`490`	`490`	`* @type bool $hide_if_empty Whether to hide the drop-down if no terms exist. Default false.`
`491`	`491`	`* @type string $taxonomy The taxonomy slug.`
`492`	`492`	`* @type string $name Value of the name attribute to use for the drop-down select element.`
Original file line number	Diff line number	Diff line change
`@@ -4016,7 +4016,7 @@ function wp_get_shortlink( $id = 0, $context = 'post', $allow_slugs = true ) {`
`4016`	`4016`	`/**`
`4017`	`4017`	`* Filters whether to preempt generating a shortlink for the given post.`
`4018`	`4018`	`*`
`4019`		`- * Returning a truthy value from the filter will effectively short-circuit`
	`4019`	`+ * Returning a value other than false from the filter will short-circuit`
`4020`	`4020`	`* the shortlink generation process, returning that value instead.`
`4021`	`4021`	`*`
`4022`	`4022`	`* @since 3.0.0`
Original file line number	Diff line number	Diff line change
`@@ -4535,9 +4535,8 @@ function wp_enqueue_media( $args = array() ) {`
`4535`	`4535`	`*`
`4536`	`4536`	`* @link https://core.trac.wordpress.org/ticket/31071`
`4537`	`4537`	`*`
`4538`		- * @param array\|null $months An array of objects with `month` and `year`
`4539`		- * properties, or `null` (or any other non-array value)
`4540`		`- * for default behavior.`
	`4538`	+ * @param stdClass[]\|null $months An array of objects with `month` and `year`
	`4539`	+ * properties, or `null` for default behavior.
`4541`	`4540`	`*/`
`4542`	`4541`	`$months = apply_filters( 'media_library_months_with_files', null );`
`4543`	`4542`	`if ( ! is_array( $months ) ) {`
Original file line number	Diff line number	Diff line change
`@@ -1635,15 +1635,15 @@ function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {`
`1635`	`1635`	`}`
`1636`	`1636`
`1637`	`1637`	`/**`
`1638`		`- * Retrieves a list of registered meta keys for an object type.`
	`1638`	`+ * Retrieves a list of registered metadata args for an object type, keyed by their meta keys.`
`1639`	`1639`	`*`
`1640`	`1640`	`* @since 4.6.0`
`1641`	`1641`	* @since 4.9.8 The `$object_subtype` parameter was added.
`1642`	`1642`	`*`
`1643`	`1643`	`* @param string $object_type Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',`
`1644`	`1644`	`* or any other object type with an associated meta table.`
`1645`	`1645`	`* @param string $object_subtype Optional. The subtype of the object type.`
`1646`		`- * @return string[] List of registered meta keys.`
	`1646`	`+ * @return array[] List of registered metadata args, keyed by their meta keys.`
`1647`	`1647`	`*/`
`1648`	`1648`	`function get_registered_meta_keys( $object_type, $object_subtype = '' ) {`
`1649`	`1649`	`global $wp_meta_keys;`
Original file line number	Diff line number	Diff line change
`@@ -114,8 +114,8 @@ function get_option( $option, $default = false ) {`
`114`	`114`	`*`
`115`	`115`	* The dynamic portion of the hook name, `$option`, refers to the option name.
`116`	`116`	`*`
`117`		`- * Returning a truthy value from the filter will effectively short-circuit retrieval`
`118`		`- * and return the passed value instead.`
	`117`	`+ * Returning a value other than false from the filter will short-circuit retrieval`
	`118`	`+ * and return that value instead.`
`119`	`119`	`*`
`120`	`120`	`* @since 1.5.0`
`121`	`121`	* @since 4.4.0 The `$option` parameter was added.
`@@ -832,8 +832,8 @@ function get_transient( $transient ) {`
`832`	`832`	`*`
`833`	`833`	* The dynamic portion of the hook name, `$transient`, refers to the transient name.
`834`	`834`	`*`
`835`		`- * Returning a truthy value from the filter will effectively short-circuit retrieval`
`836`		`- * and return the passed value instead.`
	`835`	`+ * Returning a value other than false from the filter will short-circuit retrieval`
	`836`	`+ * and return that value instead.`
`837`	`837`	`*`
`838`	`838`	`* @since 2.8.0`
`839`	`839`	* @since 4.4.0 The `$transient` parameter was added
`@@ -1004,6 +1004,8 @@ function set_transient( $transient, $value, $expiration = 0 ) {`
`1004`	`1004`	`/**`
`1005`	`1005`	`* Deletes all expired transients.`
`1006`	`1006`	`*`
	`1007`	`+ * Note that this function won't do anything if an external object cache is in use.`
	`1008`	`+ *`
`1007`	`1009`	`* The multi-table delete syntax is used to delete the transient record`
`1008`	`1010`	`* from table a, and the corresponding transient_timeout record from table b.`
`1009`	`1011`	`*`
`@@ -1132,9 +1134,9 @@ function get_user_setting( $name, $default = false ) {`
`1132`	`1134`	`/**`
`1133`	`1135`	`* Adds or updates user interface setting.`
`1134`	`1136`	`*`
`1135`		`- * Both $name and $value can contain only ASCII letters, numbers, hyphens, and underscores.`
	`1137`	+ * Both `$name` and `$value` can contain only ASCII letters, numbers, hyphens, and underscores.
`1136`	`1138`	`*`
`1137`		`- * This function has to be used before any output has started as it calls setcookie().`
	`1139`	+ * This function has to be used before any output has started as it calls `setcookie()`.
`1138`	`1140`	`*`
`1139`	`1141`	`* @since 2.8.0`
`1140`	`1142`	`*`
`@@ -1159,7 +1161,7 @@ function set_user_setting( $name, $value ) {`
`1159`	`1161`	`*`
`1160`	`1162`	`* Deleting settings would reset them to the defaults.`
`1161`	`1163`	`*`
`1162`		`- * This function has to be used before any output has started as it calls setcookie().`
	`1164`	+ * This function has to be used before any output has started as it calls `setcookie()`.
`1163`	`1165`	`*`
`1164`	`1166`	`* @since 2.7.0`
`1165`	`1167`	`*`
`@@ -1389,8 +1391,8 @@ function get_network_option( $network_id, $option, $default = false ) {`
`1389`	`1391`	`*`
`1390`	`1392`	* The dynamic portion of the hook name, `$option`, refers to the option name.
`1391`	`1393`	`*`
`1392`		`- * Returning a truthy value from the filter will effectively short-circuit retrieval`
`1393`		`- * and return the passed value instead.`
	`1394`	`+ * Returning a value other than false from the filter will short-circuit retrieval`
	`1395`	`+ * and return that value instead.`
`1394`	`1396`	`*`
`1395`	`1397`	`* @since 2.9.0 As 'pre_site_option_' . $key`
`1396`	`1398`	`* @since 3.0.0`
`@@ -1420,7 +1422,7 @@ function get_network_option( $network_id, $option, $default = false ) {`
`1420`	`1422`	`if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {`
`1421`	`1423`
`1422`	`1424`	`/**`
`1423`		`- * Filters a specific default network option.`
	`1425`	`+ * Filters the value of a specific default network option.`
`1424`	`1426`	`*`
`1425`	`1427`	* The dynamic portion of the hook name, `$option`, refers to the option name.
`1426`	`1428`	`*`