[wp-trac] [WordPress Trac] #53471: `wp_list_categories()` doc block is missing `hide_empty` argument

[WordPress Trac]

#53471: `wp_list_categories()` doc block is missing `hide_empty` argument
-----------------------------+------------------------------
 Reporter:  audrasjb         |       Owner:  (none)
     Type:  defect (bug)     |      Status:  new
 Priority:  normal           |   Milestone:  Awaiting Review
Component:  Taxonomy         |     Version:
 Severity:  normal           |  Resolution:
 Keywords:  has-patch close  |     Focuses:  docs
-----------------------------+------------------------------
Changes (by SergeyBiryukov):

 * keywords:  has-patch => has-patch close


Comment:

 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 [source:tags/5.7.2/src/wp-
 includes/category-template.php?marks=486,487#L478 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.

 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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/53471#comment:2>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform