Docs: Clarify the significance of the $accepted_args parameter value in the documentation for add_filter().

Adds a couple of examples to illustrate callbacks accepting a variable number of arguments.

Fixes #33862.


git-svn-id: https://develop.svn.wordpress.org/trunk@34288 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/plugin.php

@@ -54,13 +54,35 @@ if ( ! isset( $wp_current_filter ) )
  *     }
  *     add_filter( 'example_filter', 'example_callback' );
  *
- * Since WordPress 1.5.1, bound callbacks can take as many arguments as are
- * passed as parameters in the corresponding apply_filters() call. The `$accepted_args`
- * parameter allows for calling functions only when the number of args match.
+ * Bound callbacks can accept from none to the total number of arguments passed as parameters
+ * in the corresponding apply_filters() call.
  *
- * *Note:* the function will return true whether or not the callback is valid.
- * It is up to you to take care. This is done for optimization purposes,
- * so everything is as quick as possible.
+ * In other words, if an apply_filters() call passes four total arguments, callbacks bound to
+ * it can accept none (the same as 1) of the arguments or up to four. The important part is that
+ * the `$accepted_args` value must reflect the number of arguments the bound callback *actually*
+ * opted to accept. If no arguments were accepted by the callback that is considered to be the
+ * same as accepting 1 argument. For example:
+ *
+ *     // Filter call.
+ *     $value = apply_filters( 'hook', $value, $arg2, $arg3 );
+ *
+ *     // Accepting zero/one arguments.
+ *     function example_callback() {
+ *         ...
+ *         return 'some value';
+ *     }
+ *     add_filter( 'hook', 'example_callback' ); // Where $priority is default 10, $accepted_args is default 1.
+ *
+ *     // Accepting two arguments (three possible).
+ *     function example_callback( $value, $arg2 ) {
+ *         ...
+ *         return $maybe_modified_value;
+ *     }
+ *     add_filter( 'hook', 'example_callback', 10, 2 ); // Where $priority is 10, $accepted_args is 2.
+ *
+ * *Note:* The function will return true whether or not the callback is valid.
+ * It is up to you to take care. This is done for optimization purposes, so
+ * everything is as quick as possible.
  *
  * @since 0.71
  *