Changeset 53827

Timestamp:

08/04/2022 02:50:27 PM (2 years ago)

Author:

johnbillion

Message:

Docs: Various corrections and improvements to inline documentation.

See #55646

Location:

trunk/src

Files:

• wp-admin/authorize-application.php (modified) (1 diff)
• wp-admin/edit-tags.php (modified) (1 diff)
• wp-includes/category.php (modified) (1 diff)
• wp-includes/class-wp-comment-query.php (modified) (2 diffs)
• wp-includes/class-wp-http.php (modified) (1 diff)
• wp-includes/class-wp-query.php (modified) (1 diff)
• wp-includes/link-template.php (modified) (1 diff)
• wp-includes/media.php (modified) (1 diff)
• wp-includes/meta.php (modified) (2 diffs)
• wp-includes/option.php (modified) (7 diffs)
• wp-includes/pluggable.php (modified) (1 diff)
• wp-includes/taxonomy.php (modified) (1 diff)
• wp-login.php (modified) (1 diff)

trunk/src/wp-admin/authorize-application.php

@@ -251 +251 @@
                  *
                  *     @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.

trunk/src/wp-admin/edit-tags.php

@@ -487 +487 @@
          *     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.

trunk/src/wp-includes/category.php

@@ -270 +270 @@
  * @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 ) {

trunk/src/wp-includes/class-wp-comment-query.php

@@ -160 +160 @@
      *     @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
@@ -224 +223 @@
      *     @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.

trunk/src/wp-includes/class-wp-http.php

@@ -688 +688 @@
      *
      *     @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.

trunk/src/wp-includes/class-wp-query.php

@@ -666 +666 @@
      *                                                    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.

trunk/src/wp-includes/link-template.php

@@ -4017 +4017 @@
      * 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.
      *

trunk/src/wp-includes/media.php

@@ -4536 +4536 @@
      * @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 );

trunk/src/wp-includes/meta.php

@@ -1636 +1636 @@
 
 /**
- * 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
@@ -1644 +1644 @@
  *                               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 = '' ) {

trunk/src/wp-includes/option.php

@@ -115 +115 @@
      * 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
@@ -833 +833 @@
      * 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
@@ -1004 +1004 @@
 /**
  * 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
@@ -1133 +1135 @@
  * Adds or updates user interface setting.
  *
- * 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().
+ * 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()`.
  *
  * @since 2.8.0
@@ -1160 +1162 @@
  * 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
@@ -1390 +1392 @@
      * 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
@@ -1421 +1423 @@
 
         /**
-         * 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.

trunk/src/wp-includes/pluggable.php

@@ -896 +896 @@
      *
      * @since 2.7.0
+     * @since 4.0.0 The `$token` element was added to the return value.
      *
      * @param string $cookie Authentication cookie.

trunk/src/wp-includes/taxonomy.php

@@ -3106 +3106 @@
  * @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.

trunk/src/wp-login.php

@@ -348 +348 @@
                     /**
                      * 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