WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 18 months ago

Last modified 18 months ago

#37402 closed task (blessed) (fixed)

Standardise documentation for variadic functions

Reported by: johnbillion Owned by: johnbillion
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)

#1 @johnbillion
3 years ago

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:

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

@param type $name,... Description

#2 @mariovalney
3 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?

#3 @johnbillion
18 months ago

In 45418:

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

See #37402

#4 @johnbillion
18 months ago

  • Milestone changed from Future Release to 5.3

#5 @johnbillion
18 months ago

In 45419:

Docs: Standardise documentation for capability-related variadic functions.

See #37402

#6 @johnbillion
18 months ago

In 45420:

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

See #37402

#7 @johnbillion
18 months ago

In 45421:

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

See #37402

#8 @johnbillion
18 months ago

In 45422:

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

See #37402

#9 @johnbillion
18 months ago

In 45449:

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

See #37402

#10 @johnbillion
18 months ago

  • Owner set to johnbillion
  • Resolution set to fixed
  • Status changed from new to closed

In 45450:

Docs: Improve documentation for some more variadic functions.

Fixes #37402

#11 @johnbillion
18 months ago

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

Note: See TracTickets for help on using tickets.