Changeset 48473

Timestamp:

07/14/2020 11:54:26 AM (3 years ago)

Author:

johnbillion

Message:

Docs: Correct and improve inline docs for parameters that accept a callback function.

See #49572

Location:

trunk/src

Files:

• wp-admin/includes/ajax-actions.php (modified) (2 diffs)
• wp-admin/includes/class-wp-screen.php (modified) (1 diff)
• wp-admin/includes/class-wp-site-health.php (modified) (1 diff)
• wp-admin/includes/nav-menu.php (modified) (2 diffs)
• wp-includes/class-wp-customize-control.php (modified) (1 diff)
• wp-includes/class-wp-customize-setting.php (modified) (1 diff)
• wp-includes/comment-template.php (modified) (1 diff)
• wp-includes/functions.php (modified) (2 diffs)
• wp-includes/meta.php (modified) (1 diff)
• wp-includes/widgets.php (modified) (2 diffs)

trunk/src/wp-admin/includes/ajax-actions.php

@@ -4779 +4779 @@
      *         Array of personal data exporters.
      *
-     *         @type string $callback               Callable exporter function that accepts an
-     *                                              email address and a page and returns an array
-     *                                              of name => value pairs of personal data.
-     *         @type string $exporter_friendly_name Translated user facing friendly name for the
-     *                                              exporter.
+     *         @type callable $callback               Callable exporter function that accepts an
+     *                                                email address and a page and returns an array
+     *                                                of name => value pairs of personal data.
+     *         @type string   $exporter_friendly_name Translated user facing friendly name for the
+     *                                                exporter.
      *     }
      * }
@@ -4969 +4969 @@
      *         Array of personal data exporters.
      *
-     *         @type string $callback               Callable eraser that accepts an email address and
-     *                                              a page and returns an array with boolean values for
-     *                                              whether items were removed or retained and any messages
-     *                                              from the eraser, as well as if additional pages are
-     *                                              available.
-     *         @type string $exporter_friendly_name Translated user facing friendly name for the eraser.
+     *         @type callable $callback               Callable eraser that accepts an email address and
+     *                                                a page and returns an array with boolean values for
+     *                                                whether items were removed or retained and any messages
+     *                                                from the eraser, as well as if additional pages are
+     *                                                available.
+     *         @type string   $exporter_friendly_name Translated user facing friendly name for the eraser.
      *     }
      * }

trunk/src/wp-admin/includes/class-wp-screen.php

@@ -621 +621 @@
      *     Array of arguments used to display the help tab.
      *
-     *     @type string $title    Title for the tab. Default false.
-     *     @type string $id       Tab ID. Must be HTML-safe and should be unique for this menu.
-     *                            It is NOT allowed to contain any empty spaces. Default false.
-     *     @type string $content  Optional. Help tab content in plain text or HTML. Default empty string.
-     *     @type string $callback Optional. A callback to generate the tab content. Default false.
-     *     @type int    $priority Optional. The priority of the tab, used for ordering. Default 10.
+     *     @type string   $title    Title for the tab. Default false.
+     *     @type string   $id       Tab ID. Must be HTML-safe and should be unique for this menu.
+     *                              It is NOT allowed to contain any empty spaces. Default false.
+     *     @type string   $content  Optional. Help tab content in plain text or HTML. Default empty string.
+     *     @type callable $callback Optional. A callback to generate the tab content. Default false.
+     *     @type int      $priority Optional. The priority of the tab, used for ordering. Default 10.
      * }
      */

trunk/src/wp-admin/includes/class-wp-site-health.php

@@ -148 +148 @@
      * @since 5.4.0
      *
-     * @param $callback
+     * @param callable $callback
      * @return mixed|void
      */

trunk/src/wp-admin/includes/nav-menu.php

@@ -333 +333 @@
  *     @type string       $id       Meta box 'id' attribute.
  *     @type string       $title    Meta box title.
- *     @type string       $callback Meta box display callback.
+ *     @type callable     $callback Meta box display callback.
  *     @type WP_Post_Type $args     Extra meta box arguments (the post type object for this meta box).
  * }
@@ -685 +685 @@
  *     Taxonomy menu item meta box arguments.
  *
- *     @type string $id       Meta box 'id' attribute.
- *     @type string $title    Meta box title.
- *     @type string $callback Meta box display callback.
- *     @type object $args     Extra meta box arguments (the taxonomy object for this meta box).
+ *     @type string   $id       Meta box 'id' attribute.
+ *     @type string   $title    Meta box title.
+ *     @type callable $callback Meta box display callback.
+ *     @type object   $args     Extra meta box arguments (the taxonomy object for this meta box).
  * }
  */

trunk/src/wp-includes/class-wp-customize-control.php

@@ -205 +205 @@
      *                                                 input types such as 'email', 'url', 'number', 'hidden', and
      *                                                 'date' are supported implicitly. Default 'text'.
-     *     @type callback             $active_callback Active callback.
+     *     @type callable             $active_callback Active callback.
      * }
      */

trunk/src/wp-includes/class-wp-customize-setting.php

@@ -98 +98 @@
      *
      * @since 3.4.0
-     * @var string
+     * @var callable
      */
     public $sanitize_js_callback = '';

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

@@ -2008 +2008 @@
  *     Optional. Formatting options.
  *
- *     @type object $walker            Instance of a Walker class to list comments. Default null.
- *     @type int    $max_depth         The maximum comments depth. Default empty.
- *     @type string $style             The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.
- *     @type string $callback          Callback function to use. Default null.
- *     @type string $end-callback      Callback function to use at the end. Default null.
- *     @type string $type              Type of comments to list.
- *                                     Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'.
- *     @type int    $page              Page ID to list comments for. Default empty.
- *     @type int    $per_page          Number of comments to list per page. Default empty.
- *     @type int    $avatar_size       Height and width dimensions of the avatar size. Default 32.
- *     @type bool   $reverse_top_level Ordering of the listed comments. If true, will display newest comments first.
- *     @type bool   $reverse_children  Whether to reverse child comments in the list. Default null.
- *     @type string $format            How to format the comments list.
- *                                     Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'.
- *     @type bool   $short_ping        Whether to output short pings. Default false.
- *     @type bool   $echo              Whether to echo the output or return it. Default true.
+ *     @type object   $walker            Instance of a Walker class to list comments. Default null.
+ *     @type int      $max_depth         The maximum comments depth. Default empty.
+ *     @type string   $style             The style of list ordering. Default 'ul'. Accepts 'ul', 'ol'.
+ *     @type callable $callback          Callback function to use. Default null.
+ *     @type callable $end-callback      Callback function to use at the end. Default null.
+ *     @type string   $type              Type of comments to list.
+ *                                       Default 'all'. Accepts 'all', 'comment', 'pingback', 'trackback', 'pings'.
+ *     @type int      $page              Page ID to list comments for. Default empty.
+ *     @type int      $per_page          Number of comments to list per page. Default empty.
+ *     @type int      $avatar_size       Height and width dimensions of the avatar size. Default 32.
+ *     @type bool     $reverse_top_level Ordering of the listed comments. If true, will display newest comments first.
+ *     @type bool     $reverse_children  Whether to reverse child comments in the list. Default null.
+ *     @type string   $format            How to format the comments list.
+ *                                       Default 'html5' if the theme supports it. Accepts 'html5', 'xhtml'.
+ *     @type bool     $short_ping        Whether to output short pings. Default false.
+ *     @type bool     $echo              Whether to echo the output or return it. Default true.
  * }
  * @param WP_Comment[] $comments Optional. Array of WP_Comment objects.

trunk/src/wp-includes/functions.php

@@ -4150 +4150 @@
 
 /**
- * Checks that a JSONP callback is a valid JavaScript callback.
+ * Checks that a JSONP callback is a valid JavaScript callback name.
  *
  * Only allows alphanumeric characters and the dot character in callback
@@ -4158 +4158 @@
  * @since 4.6.0
  *
- * @param string $callback Supplied JSONP callback function.
- * @return bool True if valid callback, otherwise false.
+ * @param string $callback Supplied JSONP callback function name.
+ * @return bool Whether the callback function name is valid.
  */
 function wp_check_jsonp_callback( $callback ) {

trunk/src/wp-includes/meta.php

@@ -1241 +1241 @@
  *                                         In other words, when calling get_metadata() with `$single` set to `false`,
  *                                         the default value given here will be wrapped in an array.
- *     @type string     $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
- *     @type string     $auth_callback     Optional. A function or method to call when performing edit_post_meta,
+ *     @type callable   $sanitize_callback A function or method to call when sanitizing `$meta_key` data.
+ *     @type callable   $auth_callback     Optional. A function or method to call when performing edit_post_meta,
  *                                         add_post_meta, and delete_post_meta capability checks.
  *     @type bool|array $show_in_rest      Whether data associated with this meta key can be considered public and

trunk/src/wp-includes/widgets.php

@@ -788 +788 @@
          *     An associative array of widget arguments.
          *
-         *     @type string $name                Name of the widget.
-         *     @type string $id                  Widget ID.
-         *     @type array|callable $callback    When the hook is fired on the front end, $callback is an array
-         *                                       containing the widget object. Fired on the back end, $callback
-         *                                       is 'wp_widget_control', see $_callback.
-         *     @type array          $params      An associative array of multi-widget arguments.
-         *     @type string         $classname   CSS class applied to the widget container.
-         *     @type string         $description The widget description.
-         *     @type array          $_callback   When the hook is fired on the back end, $_callback is populated
-         *                                       with an array containing the widget object, see $callback.
+         *     @type string   $name        Name of the widget.
+         *     @type string   $id          Widget ID.
+         *     @type callable $callback    When the hook is fired on the front end, $callback is an array
+         *                                 containing the widget object. Fired on the back end, $callback
+         *                                 is 'wp_widget_control', see $_callback.
+         *     @type array    $params      An associative array of multi-widget arguments.
+         *     @type string   $classname   CSS class applied to the widget container.
+         *     @type string   $description The widget description.
+         *     @type array    $_callback   When the hook is fired on the back end, $_callback is populated
+         *                                 with an array containing the widget object, see $callback.
          * }
          */
@@ -858 +858 @@
  * @global array $wp_registered_widgets
  *
- * @param string|false $callback      Optional, Widget callback to check. Default false.
- * @param int|false    $widget_id     Optional. Widget ID. Optional, but needed for checking. Default false.
- * @param string|false $id_base       Optional. The base ID of a widget created by extending WP_Widget. Default false.
- * @param bool         $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. Default true.
+ * @param callable|false $callback      Optional, Widget callback to check. Default false.
+ * @param int|false      $widget_id     Optional. Widget ID. Optional, but needed for checking. Default false.
+ * @param string|false   $id_base       Optional. The base ID of a widget created by extending WP_Widget. Default false.
+ * @param bool           $skip_inactive Optional. Whether to check in 'wp_inactive_widgets'. Default true.
  * @return string|false False if widget is not active or id of sidebar in which the widget is active.
  */