[wp-trac] [WordPress Trac] #47896: Docs: add missing argument in the wp_list_categories function docblock

[WordPress Trac]

#47896: Docs: add missing argument in the wp_list_categories function docblock
-----------------------------------+------------------------------
 Reporter:  audrasjb               |       Owner:  (none)
     Type:  defect (bug)           |      Status:  new
 Priority:  normal                 |   Milestone:  Awaiting Review
Component:  Taxonomy               |     Version:
 Severity:  normal                 |  Resolution:
 Keywords:  has-patch 2nd-opinion  |     Focuses:  docs
-----------------------------------+------------------------------

Comment (by boonebgorges):

 Replying to [comment:2 birgire]:

 > The way I see it now, is that it's good if we can **avoid duplicating
 the documentation** of input arguments if  possible and only document it
 if it's a part of the corresponding function's code base. Then e.g. refer
 to the other places where the other "hidden" but supported input arguments
 are documented.

 I agree with this. 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`).

 My suggested changes are in [attachment:"47896.3.diff"]

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