wp_dropdown_categories documentation is missing arguments

[ArnaudBan]

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.

[ArnaudBan]

I uploaded 41058.diff​ to fixe the documentation.

[boonebgorges]

Thanks for the patch, @ArnaudBan !

[boonebgorges]

In 40903:

Simplify documentation for wp_dropdown_categories().

Props ArnaudBan.
Fixes #41058.

[SergeyBiryukov]

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?

[ArnaudBan]

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.

[SergeyBiryukov]

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.

[theMikeD]

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.

[boonebgorges]

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.

[DrewAPicture]

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.

[SergeyBiryukov]

In 41767:

Taxonomy: After [40903], restore documentation for wp_dropdown_categories() arguments that are different from the defaults in WP_Term_Query::__construct().

Fixes #41058.