Changeset 53302

Timestamp:

04/28/2022 09:57:51 AM (4 years ago)

Author:

johnbillion

Message:

Docs: Various docblock corrections and improvements for changes introduced in 6.0.

See #54729

Location:

trunk/src

Files:

• wp-admin/includes/class-wp-media-list-table.php (modified) (1 diff)
• wp-admin/includes/image-edit.php (modified) (1 diff)
• wp-includes/block-editor.php (modified) (1 diff)
• wp-includes/blocks.php (modified) (5 diffs)
• wp-includes/class-wp-term-query.php (modified) (1 diff)
• wp-includes/class-wp-theme-json-resolver.php (modified) (1 diff)
• wp-includes/class-wp-theme-json.php (modified) (1 diff)
• wp-includes/rest-api/endpoints/class-wp-rest-block-pattern-categories-controller.php (modified) (1 diff)
• wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php (modified) (1 diff)
• wp-includes/sitemaps/providers/class-wp-sitemaps-taxonomies.php (modified) (1 diff)
• wp-includes/widgets/class-wp-widget-media.php (modified) (2 diffs)

trunk/src/wp-admin/includes/class-wp-media-list-table.php

@@ -510 +510 @@
 
                 /**
-                 * Filters the published time of the post.
+                 * Filters the published time of an attachment displayed in the Media list table.
                  *
                  * @since 6.0.0
                  *
                  * @param string  $h_time      The published time.
-                 * @param WP_Post $post        Post object.
+                 * @param WP_Post $post        Attachment object.
                  * @param string  $column_name The column name.
                  */

trunk/src/wp-admin/includes/image-edit.php

@@ -50 +50 @@
          * @since 6.0.0
          *
-         * @param bool|array $edit_custom_sizes True if custom sizes can be edited or array of custom sizes.
+         * @param bool|string[] $edit_custom_sizes True if custom sizes can be edited or array of custom size names.
          */
         $edit_custom_sizes = apply_filters( 'edit_custom_thumbnail_sizes', $edit_custom_sizes );

trunk/src/wp-includes/block-editor.php

@@ -296 +296 @@
  * @global string $pagenow The filename of the current screen.
  *
- * @return array The block editor assets: styles and scripts.
+ * @return array {
+ *     The block editor assets.
+ *
+ *     @type string|false $styles  String containing the HTML for styles.
+ *     @type string|false $scripts String containing the HTML for scripts.
+ * }
  */
 function _wp_get_iframed_editor_assets() {

trunk/src/wp-includes/blocks.php

@@ -1194 +1194 @@
 
 /**
- * Helper function that returns the proper pagination arrow html for
+ * Helper function that returns the proper pagination arrow HTML for
  * `QueryPaginationNext` and `QueryPaginationPrevious` blocks based
  * on the provided `paginationArrow` from `QueryPagination` context.
@@ -1205 +1205 @@
  * @param boolean  $is_next Flag for handling `next/previous` blocks.
  *
- * @return string|null Returns the constructed WP_Query arguments.
+ * @return string|null The pagination arrow HTML or null if there is none.
  */
 function get_query_pagination_arrow( $block, $is_next ) {
@@ -1283 +1283 @@
  *
  * @return array Returns the comment query parameters to use with the
- * WP_Comment_Query constructor.
+ *               WP_Comment_Query constructor.
  */
 function build_comment_query_vars_from_block( $block ) {
@@ -1340 +1340 @@
 
 /**
- * Helper function that returns the proper pagination arrow html for
+ * Helper function that returns the proper pagination arrow HTML for
  * `CommentsPaginationNext` and `CommentsPaginationPrevious` blocks based on the
  * provided `paginationArrow` from `CommentsPagination` context.
@@ -1352 +1352 @@
  *                                  Default 'next'. Accepts 'next' or 'previous'.
  *
- * @return string|null Returns the constructed WP_Query arguments.
+ * @return string|null The pagination arrow HTML or null if there is none.
  */
 function get_comments_pagination_arrow( $block, $pagination_type = 'next' ) {

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

@@ -952 +952 @@
          *
          * @param WP_Term[] $term_objects Array of term objects.
-         * @param string $_fields Field to format.
+         * @param string    $_fields      Field to format.
          *
          * @return WP_Term[]|int[]|string[] Array of terms / strings / ints depending on field requested.

trunk/src/wp-includes/class-wp-theme-json-resolver.php

@@ -152 +152 @@
          * @since 5.8.0
          * @since 5.9.0 Theme supports have been inlined and the `$theme_support_data` argument removed.
-         * @since 6.0.0 Adds a second parameter to allow the theme data to be returned without theme supports.
+         * @since 6.0.0 Added an `$options` parameter to allow the theme data to be returned without theme supports.
          *
          * @param array $deprecated Deprecated. Not used.
-         * @param array $options Contains a key called with_supports to determine whether to include theme supports in the data.
+         * @param array $options {
+         *     Options arguments.
+         *
+         *     @type bool $with_supports Whether to include theme supports in the data. Default true.
+         * }
          * @return WP_Theme_JSON Entity that holds theme data.
          */

trunk/src/wp-includes/class-wp-theme-json.php

@@ -1539 +1539 @@
          * @since 6.0.0
          *
-         * @param array      $data The data to inspect.
-         * @param bool|array $path Boolean or path to a boolean.
+         * @param array      $data    The data to inspect.
+         * @param bool|array $path    Boolean or path to a boolean.
          * @param bool       $default Default value if the referenced path is missing.
-         * @return boolean
+         *                            Default false.
+         * @return bool Value of boolean metadata.
          */
         protected static function get_metadata_boolean( $data, $path, $default = false ) {

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-block-pattern-categories-controller.php

@@ -97 +97 @@
          * @since 6.0.0
          *
-         * @param object          $item    Raw category as registered, before any changes.
+         * @param array           $item    Raw category as registered, before any changes.
          * @param WP_REST_Request $request Request object.
          * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php

@@ -113 +113 @@
          * @since 6.0.0
          *
-         * @param object          $item    Raw pattern as registered, before any changes.
+         * @param array           $item    Raw pattern as registered, before any changes.
          * @param WP_REST_Request $request Request object.
          * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.

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

@@ -119 +119 @@
                                  *
                                  * @since 5.5.0
-                                 * @since 6.0.0 Added fourth argument for the term object.
+                                 * @since 6.0.0 Added `$term` argument containing the term object.
                                  *
                                  * @param array   $sitemap_entry Sitemap entry for the term.

trunk/src/wp-includes/widgets/class-wp-widget-media.php

@@ -468 +468 @@
          * @since 6.0.0
          *
-         * @var string
+         * @return string
          */
         protected static function get_default_description() {
@@ -484 +484 @@
          * @since 6.0.0
          *
-         * @return string[]
+         * @return (string|array)[]
          */
         protected static function get_l10n_defaults() {