Docs: add missing argument in the wp_list_categories function docblock

[audrasjb]

The 'include' input argument is missing in the wp_list_categories() function's DocBlock.

Indeed, it is possible to use the include argument to only include categories from the defined array/string.
This parameter is fully documented in WP_Term_Query: ​https://developer.wordpress.org/reference/classes/wp_term_query/__construct/

Previously mentioned (but not fixed) in #36693.

[audrasjb]

Document include argument in wp_list_categories()

[audrasjb]

Wondering if we should also edit exclude documentation to be consistent with ​the existing documentation bits.

'exclude'
(array|string) Array or comma/space-separated string of term ids to exclude. 
If $include is non-empty, $exclude is ignored. Default empty array.

[birgire]

Hi @audrasjb

yes, these are good considerations.

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.

So I would suggest not document include in wp_list_categories() as it's not part of it's code base, like exclude, but refer e.g. other "hidden" arguments to the corresponding part of WP_Term_Query where it's fully documented.

I might be wrong about this, but just wanted to mention it here :-)

[audrasjb]

Hi @birgire , these are also good considerations :)

While I understand the idea for not duplicating documentation bits, I'd say that in this case, that would be better to refer to the existing documentation, like, for example:

/**
 * Display or retrieve the HTML list of categories.
 *
 * @see get_terms() for the full list of arguments.
 *
 …

[birgire]

Replying to audrasjb:

Hi @birgire , these are also good considerations :)

While I understand the idea for not duplicating documentation bits, I'd say that in this case, that would be better to refer to the existing documentation, like, for example:

/**
 * Display or retrieve the HTML list of categories.
 *
 * @see get_terms() for the full list of arguments.
 *
 …

I think I would suggest referring to get_categories() instead as it's explicitly used.

I remember the discussion when we adjusted the wp_tag_cloud documentation:

​https://developer.wordpress.org/reference/functions/wp_tag_cloud/

in #42019. That's one way to refer to the other supported input arguments.

We can see similarly, how the input arguments for the get_categories() input arguments are documented:

https://core.trac.wordpress.org/browser/tags/5.2.2/src/wp-includes/category.php#L9

PS:

Also mentioned by @DrewAPicture:

We're working on getting top-level @see tags displayed in code reference articles via ​#meta3165, so that would be the preferred method for cross-referencing functions via the docs.

in https://core.trac.wordpress.org/ticket/42019#comment:11

[itowhid06]

I might be wrong, but from my point of view wp_list_categories uses get_categories which uses get_terms; and get_terms supports include as a argument. So basically even if include is not part of the codebase of wp_list_categories, it completely supports it. So my opinion is to make include as part of wp_list_categories. May I suggest 47896.2.diff?

[boonebgorges]

Replying to 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 47896.3.diff​

[audrasjb]

Makes sense :)
47896.3.diff is a perfect compromise 👍

[boonebgorges]

In 45894:

Taxonomy: Standardize docs for wp_list_categories().

Many of the parameters historically documented on this function are merely
passed through to get_categories() and its underlying functions. In order to
avoid unnecessary duplication of function arguments, we remove documentation of
these parameters, and replace it with reference to the wrapped functions.

Parameters that receive special treatment or are otherwise changed before
being passed through continue to be documented as part of wp_list_categories().

Props audrasjb, itowhid06, birgire.
Fixes #47896.

[SergeyBiryukov]

Replying to boonebgorges:

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).

For reference, this was previously discussed in #41058, specifically comment:8:ticket:41058.

[SergeyBiryukov]

In 45895:

Docs: Reference WP_Term_Query::__construct() in wp_list_categories() DocBlock for additional accepted arguments.

Clarify that wp_dropdown_categories() always returns a string, regardless of the echo parameter.

See #47896, #47110.

[SergeyBiryukov]

In 49060:

Taxonomy: Restore documentation for the taxonomy parameter of wp_list_categories().

The parameter's default value is different from the one in WP_Term_Query::__construct(), and should be documented accordingly.

This also clarifies that the taxonomy parameter of wp_list_categories() only accepts a string, not an array.

Follow-up to [40903], [41767], [45894], [45895].

Props grapplerulrich, mukesh27, TimothyBlynJacobs, SergeyBiryukov.
Fixes #51378. See #47896.