#37402 closed task (blessed) (fixed)
Standardise documentation for variadic functions
Reported by: |
|
Owned by: |
|
---|---|---|---|
Milestone: | 5.3 | Priority: | normal |
Severity: | minor | Version: | |
Component: | General | Keywords: | needs-patch needs-docs 2nd-opinion |
Focuses: | docs | Cc: |
Description
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()
Change History (11)
#2
@
7 years ago
So. For examaple, to do_action
we should do this?
* @param string $tag The name of the action to be executed. * @param mixed ...$arg Optional. Additional arguments which are passed on to the * functions hooked to the action. Default empty.
Mixing the defined parameters and adding a variadic definition to others?
PHP_CodeSniffer, phpDocumentor, and PhpStorm have all adopted this format for documenting variadic parameters:
This format matches the actual PHP 5.6+ syntax for variadic parameters. if PSR-5 ever arrives, it will also use this format.
Refs:
WordPress core currently mostly uses the older syntax which was born from the PHP RFCs for variadic parameters: