Changeset 45420

Timestamp:

05/25/2019 10:51:14 PM (6 years ago)

Author:

johnbillion

Message:

Docs: Improve and correct documentation for hook-related variadic functions.

See #37402

Location:

trunk/src/wp-includes

Files:

• class-wp-hook.php (modified) (2 diffs)
• plugin.php (modified) (6 diffs)

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

@@ -254 +254 @@
 
     /**
-     * Calls the callback functions added to a filter hook.
+     * Calls the callback functions that have been added to a filter hook.
      *
      * @since 4.7.0
      *
      * @param mixed $value The value to filter.
-     * @param array $args  Arguments to pass to callbacks.
+     * @param array $args  Additional parameters to pass to the callback functions.
      * @return mixed The filtered value after all hooked functions are applied to it.
      */
@@ -300 +300 @@
 
     /**
-     * Executes the callback functions hooked on a specific action hook.
-     *
-     * @since 4.7.0
-     *
-     * @param mixed $args Arguments to pass to the hook callbacks.
+     * Calls the callback functions that have been added to an action hook.
+     *
+     * @since 4.7.0
+     *
+     * @param array $args Parameters to pass to the callback functions.
      */
     public function do_action( $args ) {

trunk/src/wp-includes/plugin.php

@@ -142 +142 @@
 
 /**
- * Call the functions added to a filter hook.
- *
- * The callback functions attached to filter hook $tag are invoked by calling
+ * Calls the callback functions that have been added to a filter hook.
+ *
+ * The callback functions attached to the filter hook are invoked by calling
  * this function. This function can be used to create a new filter hook by
  * simply calling this function with the name of the new hook specified using
- * the $tag parameter.
- *
- * The function allows for additional arguments to be added and passed to hooks.
- *
- *     // Our filter callback function
+ * the `$tag` parameter.
+ *
+ * The function also allows for multiple additional arguments to be passed to hooks.
+ *
+ * Example usage:
+ *
+ *     // The filter callback function
  *     function example_callback( $string, $arg1, $arg2 ) {
  *         // (maybe) modify $string
@@ -159 +161 @@
  *
  *     /*
- *      * Apply the filters by calling the 'example_callback' function we
- *      * "hooked" to 'example_filter' using the add_filter() function above.
- *      * - 'example_filter' is the filter hook $tag
+ *      * Apply the filters by calling the 'example_callback()' function that's
+ *      * hooked onto `example_filter` above.
+ *      *
+ *      * - 'example_filter' is the filter hook
  *      * - 'filter me' is the value being filtered
  *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
@@ -171 +174 @@
  * @global array $wp_current_filter Stores the list of current filters with the current one last.
  *
- * @param string $tag    The name of the filter hook.
- * @param mixed  $value  The value on which the filters hooked to `$tag` are applied on.
- * @param mixed  ...$var Additional variables passed to the functions hooked to `$tag`.
+ * @param string $tag     The name of the filter hook.
+ * @param mixed  $value   The value to filter.
+ * @param mixed  ...$args Additional parameters to pass to the callback functions.
  * @return mixed The filtered value after all hooked functions are applied to it.
  */
@@ -214 +217 @@
 
 /**
- * Execute functions hooked on a specific filter hook, specifying arguments in an array.
+ * Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
  *
  * @since 3.0.0
@@ -414 +417 @@
  * specifying the name of the new hook using the `$tag` parameter.
  *
- * You can pass extra arguments to the hooks, much like you can with apply_filters().
+ * You can pass extra arguments to the hooks, much like you can with `apply_filters()`.
+ *
+ * Example usage:
+ *
+ *     // The action callback function
+ *     function example_callback( $arg1, $arg2 ) {
+ *         // (maybe) do something with the args
+ *     }
+ *     add_action( 'example_action', 'example_callback', 10, 2 );
+ *
+ *     /*
+ *      * Trigger the actions by calling the 'example_callback()' function that's
+ *      * hooked onto `example_action` above.
+ *      *
+ *      * - 'example_action' is the action hook
+ *      * - $arg1 and $arg2 are the additional arguments passed to the callback.
+ *     $value = apply_actions( 'example_action', $arg1, $arg2 );
  *
  * @since 1.2.0
@@ -489 +508 @@
 
 /**
- * Execute functions hooked on a specific action hook, specifying arguments in an array.
+ * Calls the callback functions that have been added to an action hook, specifying arguments in an array.
  *
  * @since 2.1.0
  *
  * @see do_action() This function is identical, but the arguments passed to the
- *                  functions hooked to $tag< are supplied using an array.
+ *                  functions hooked to `$tag` are supplied using an array.
  * @global array $wp_filter         Stores all of the filters
  * @global array $wp_actions        Increments the amount of times action was triggered.