Make WordPress Core

Opened 8 years ago

Closed 5 years ago

Last modified 5 years ago

#37402 closed task (blessed) (fixed)

Standardise documentation for variadic functions

Reported by: johnbillion's profile johnbillion Owned by: johnbillion's profile 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
7 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
6 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
5 years ago

In 45418:

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

See #37402

#4 @johnbillion
5 years ago

  • Milestone changed from Future Release to 5.3

#5 @johnbillion
5 years ago

In 45419:

Docs: Standardise documentation for capability-related variadic functions.

See #37402

#6 @johnbillion
5 years ago

In 45420:

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

See #37402

#7 @johnbillion
5 years ago

In 45421:

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

See #37402

#8 @johnbillion
5 years ago

In 45422:

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

See #37402

#9 @johnbillion
5 years ago

In 45449:

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

See #37402

#10 @johnbillion
5 years 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
5 years ago

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

Note: See TracTickets for help on using tickets.