Make WordPress Core

Opened 2 months ago

Last modified 3 days ago

#41058 reopened enhancement

wp_dropdown_categories documentation is missing arguments

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


wp_dropdown_categories use get_terms witch use WP_Term_Query::__construct().
The documentation should show that you can use all the WP_Term_Query::__construct() argument.

Attachments (1)

41058.diff (3.5 KB) - added by ArnaudBan 2 months ago.

Download all attachments as: .zip

Change History (10)

2 months ago

#1 @ArnaudBan
2 months ago

  • Keywords has-patch added

I uploaded 41058.diff to fixe the documentation.

#2 @boonebgorges
2 months ago

  • Milestone changed from Awaiting Review to 4.9
  • Owner set to boonebgorges
  • Status changed from new to assigned

Thanks for the patch, @ArnaudBan !

#3 @boonebgorges
2 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 40903:

Simplify documentation for wp_dropdown_categories().

Props ArnaudBan.
Fixes #41058.

#4 @SergeyBiryukov
2 months ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

Adding a reference to WP_Term_Query::__construct() is good, but what's the benefit of removing the existing entries that are also present in the $defaults array?

#5 follow-up: @ArnaudBan
2 months ago

There was a discussion about adding all the missing argument or add a reference to the documentation where to find them all. The second option was the one we choose.
Having juste some of the arguments documented but not all was considered misleading and not that good of an idea.

#6 in reply to: ↑ 5 @SergeyBiryukov
2 months ago

Replying to ArnaudBan:

Having just some of the arguments documented but not all was considered misleading and not that good of an idea.

Right, but at least all of the entries in the $defaults array should be documented, and [40903] removed some of those. I think they should be reinstated.

#7 @theMikeD
2 months ago

Looks to me like the ones removed are the ones specified in WP_Term_Query::_construct so removing them is the right DRY decision IMHO.

#8 @boonebgorges
2 months ago

We've generally moved lately toward not documenting parameters on wrapper functions if the default value doesn't differ from the lower-level function. That was my understanding when removing those lines in the doc block.

The fact that items are defined in $defaults does not, IMHO, mean that those items ought to be listed in the function docblock. We pass the parsed $r array down through lower-level functions, and our $defaults declaration acts as a safeguard against lower-level changes in default values, not necessarily as a developer guide on how to use the function.

That being said, I don't feel strongly. @SergeyBiryukov If you think that not having all of the arguments specifically spelled out here may cause confusion for developers, please go ahead and add them back.

#9 @DrewAPicture
3 days ago

I agree with @boonebgorges's primary point that we generally avoid documenting duplicated args on wrappers, however I also agree with @SergeyBiryukov on documenting everything in $defaults – but only if they actually differ from the defaults for the function this one is wrapping.

So +1 to move forward with that caveat.

Note: See TracTickets for help on using tickets.