[wp-trac] [WordPress Trac] #37402: Standardise documentation for variadic functions

[WordPress Trac]

#37402: Standardise documentation for variadic functions
--------------------------+------------------------------------------------
 Reporter:  johnbillion   |      Owner:
     Type:  task          |     Status:  new
  (blessed)               |  Milestone:  Future Release
 Priority:  normal        |    Version:
Component:  General       |   Keywords:  needs-patch needs-docs 2nd-opinion
 Severity:  minor         |
  Focuses:  docs          |
--------------------------+------------------------------------------------
 The functions listed below are variadic, meaning they accept an indefinite
 number of arguments. The inline documentation for such functions in
 WordPress is varied, and generally unclear.

 A standardised format for variadic functions should be agreed upon and
 applied to these functions.

 The following functions technically accept unlimited parameters, but in
 practice only accept up to two because they all ultimately call
 `WP_User::has_cap()`. A custom cap check could use more than two
 parameters, though.

 * `author_can()`
 * `current_user_can()`
 * `current_user_can_for_blog()`
 * `map_meta_cap()`
 * `user_can()`
 * `WP_User::has_cap()`

 The following functions are actually variadic:

 * `add_post_type_support()`
 * `add_theme_support()`
 * `apply_filters()`
 * `array_replace_recursive()`
 * `current_theme_supports()`
 * `do_action()`
 * `get_theme_support()`
 * `_register_widget_form_callback()`
 * `_register_widget_update_callback()`
 * `walk_category_dropdown_tree()`
 * `walk_category_tree()`
 * `walk_page_dropdown_tree()`
 * `Walker::paged_walk()`
 * `Walker::walk()`
 * `wp_dashboard_cached_rss_widget()`
 * `WP_HTTP_IXR_Client::query()`
 * `wp_iframe()`
 * `wp_register_sidebar_widget()`
 * `wp_register_widget_control()`
 * `wp_sprintf()`
 * `WP_Upgrader_Skin::feedback()` (plus the same in classes which extend
 it)
 * `wpdb::prepare()`

 Note that `do_action()` is irregular because its first variadic parameter
 is defined in the parameter list. This means its documentation is also
 irregular.

 Finally, this method looks variadic, but it isn't, and it needs
 refactoring and docs:

 * `WP_Dependencies::__construct()`

--
Ticket URL: <https://core.trac.wordpress.org/ticket/37402>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform