Standardise documentation for variadic functions

[johnbillion]

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()

[johnbillion]

PHP_CodeSniffer, phpDocumentor, and PhpStorm have all adopted this format for documenting variadic parameters:

@param type ...$name Description

This format matches the actual PHP 5.6+ syntax for variadic parameters. if PSR-5 ever arrives, it will also use this format.

Refs:

• ​https://github.com/squizlabs/PHP_CodeSniffer/issues/841
• ​https://github.com/phpDocumentor/fig-standards/issues/121
• ​http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list
• ​https://github.com/phpDocumentor/phpDocumentor2/issues/629

WordPress core currently mostly uses the older syntax which was born from the PHP RFCs for variadic parameters:

@param type $name,... Description

[mariovalney]

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?

[johnbillion]

In 45418:

Docs: Switch to the more common syntax for variadic function documentation.

See #37402

[johnbillion]

In 45419:

Docs: Standardise documentation for capability-related variadic functions.

See #37402

[johnbillion]

In 45420:

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

See #37402

[johnbillion]

In 45421:

Docs: Correct a function name in the do_action() documentation.

See #37402

[johnbillion]

In 45422:

Docs: Improve documentation for variadic functions relating to post type support and theme support.

See #37402

[johnbillion]

In 45449:

Docs: Improve docs for variadic functions relating to widgets and their controls.

See #37402

[johnbillion]

In 45450:

Docs: Improve documentation for some more variadic functions.

Fixes #37402

[johnbillion]

I've left the functions relating to walkers because they're a mess.