WordPress.org

Make WordPress Core

Opened 4 weeks ago

Closed 3 weeks ago

Last modified 3 weeks ago

#47896 closed defect (bug) (fixed)

Docs: add missing argument in the wp_list_categories function docblock

Reported by: audrasjb Owned by: boonebgorges
Milestone: 5.3 Priority: normal
Severity: normal Version:
Component: Taxonomy Keywords: has-patch
Focuses: docs Cc:

Description

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.

Attachments (3)

47896.diff (1.3 KB) - added by audrasjb 4 weeks ago.
Document include argument in wp_list_categories()
47896.2.diff (1.7 KB) - added by itowhid06 4 weeks ago.
47896.3.diff (3.3 KB) - added by boonebgorges 4 weeks ago.

Download all attachments as: .zip

Change History (16)

@audrasjb
4 weeks ago

Document include argument in wp_list_categories()

#1 @audrasjb
4 weeks ago

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.
Last edited 4 weeks ago by audrasjb (previous) (diff)

#2 follow-up: @birgire
4 weeks ago

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

Last edited 4 weeks ago by birgire (previous) (diff)

#3 follow-up: @audrasjb
4 weeks ago

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.
 *
 …
Last edited 4 weeks ago by audrasjb (previous) (diff)

#4 @audrasjb
4 weeks ago

  • Keywords has-patch added; needs-patch removed

#5 @audrasjb
4 weeks ago

  • Keywords 2nd-opinion added

#6 in reply to: ↑ 3 @birgire
4 weeks ago

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

Last edited 4 weeks ago by birgire (previous) (diff)

#7 @itowhid06
4 weeks ago

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?

@itowhid06
4 weeks ago

#8 in reply to: ↑ 2 ; follow-up: @boonebgorges
4 weeks ago

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

@boonebgorges
4 weeks ago

#9 @audrasjb
3 weeks ago

  • Keywords 2nd-opinion removed

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

#10 @boonebgorges
3 weeks ago

  • Milestone changed from Awaiting Review to 5.3

#11 @boonebgorges
3 weeks ago

  • Owner set to boonebgorges
  • Resolution set to fixed
  • Status changed from new to closed

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.

#12 in reply to: ↑ 8 @SergeyBiryukov
3 weeks ago

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.

#13 @SergeyBiryukov
3 weeks ago

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.

Note: See TracTickets for help on using tickets.