Make WordPress Core

Opened 3 years ago

Closed 3 years ago

#53471 closed defect (bug) (invalid)

`wp_list_categories()` doc block is missing `hide_empty` argument

Reported by: audrasjb's profile audrasjb Owned by:
Milestone: Priority: normal
Severity: normal Version:
Component: Taxonomy Keywords: has-patch
Focuses: docs Cc:

Description

The docblock used for the wp_list_categories() function is missing argument hide_empty.

This issue was raised by @ken-nguyen on devhub comments/user notes.

Attachments (1)

53471.diff (1.1 KB) - added by audrasjb 3 years ago.

Download all attachments as: .zip

Change History (4)

@audrasjb
3 years ago

#1 @audrasjb
3 years ago

  • Keywords has-patch added

#2 @SergeyBiryukov
3 years ago

  • Keywords close added

Thanks for the patch!

This was intentionally removed in [45894] / #47896 to avoid duplication, as the default for this parameter is the same as in WP_Term_Query::__construct(), which is referenced in the function documentation:

Array of optional arguments. See get_categories(), get_terms(), and WP_Term_Query::__construct() for information on additional accepted arguments.

You may find that hierarchical, order, and orderby arguments are also not expicitly documented in wp_list_categories() for the same reason.

Per @boonebgorges in comment:8:ticket:47896:

I'd spell out the principle as follows:

  1. If a function accepts arguments that are passed through, without modification, to another function, then those arguments should not be documented on the wrapper function, but there should be a reference along the lines of See get_terms() in the description of $args.
  2. The wrapper function should fully document arguments that (a) are not passed through at all (such as $title_li) or (b) are modified or play a special role in the wrapper (such as $exclude_tree).

This was also previously discussed in #41058, specifically comment:8:ticket:41058.

So a decision was made to only document parameters in wrapper functions that are different from the defaults in the underlying method or function, see [41767] or [49060] for example.

Last edited 3 years ago by SergeyBiryukov (previous) (diff)

#3 @audrasjb
3 years ago

  • Keywords close removed
  • Milestone Awaiting Review deleted
  • Resolution set to invalid
  • Status changed from new to closed

Haha yes you're right!
I see that comment on devhub, and I didn't recall why it wasn't documented directly in the function. Thanks for your good memory… better than mine! 😃

Closing as invalid.

Note: See TracTickets for help on using tickets.