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.

Built from https://develop.svn.wordpress.org/trunk@34288


git-svn-id: http://core.svn.wordpress.org/trunk@34252 1a063a9b-81f0-0310-95a4-ce76da25c4cd

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
+ * Bound callbacks can accept from none to the total number of arguments passed as parameters
- * passed as parameters in the corresponding apply_filters() call. The `$accepted_args`
+ * in the corresponding apply_filters() call.
- * parameter allows for calling functions only when the number of args match.
  *
- * *Note:* the function will return true whether or not the callback is valid.
+ * In other words, if an apply_filters() call passes four total arguments, callbacks bound to
- * It is up to you to take care. This is done for optimization purposes,
+ * it can accept none (the same as 1) of the arguments or up to four. The important part is that
- * so everything is as quick as possible.
+ * 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
  *

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.4-alpha-34287';
+$wp_version = '4.4-alpha-34288';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.