Adjust the inline docs for register_taxonomy() and WP_Taxonomy::set_props()

[birgire]

The register_taxonomy() is a wrapper for a WP_Taxonomy object.

To avoid duplication, we should adjust the inline documentation for that function.

It looks like the WP_Taxonomy::set_props() method should contain the main documentation.

Similarly one can check out the documentation of the get_posts() function, that's a wrapper for a WP_Query object.

Reference:

WP_Taxonomy::set_props()

https://core.trac.wordpress.org/browser/tags/4.8.2/src/wp-includes/class-wp-taxonomy.php#L249

register_taxonomy()
https://core.trac.wordpress.org/browser/tags/4.8.2/src/wp-includes/taxonomy.php#L371

get_posts()
https://core.trac.wordpress.org/browser/tags/4.8.2/src/wp-includes/post.php#L1646

[birgire]

Related #25150 (also #42156 and #42117)

Good-first-bug?

[stevenlinx]

So you want the docs of register_taxonomy() to be more like get_posts().

At the present, get_posts() contains shortened docs (with limited parameters) and its full doc (with all parameters) is in WP_Query::parse_query().

Do you have a suggestion on what some of the parameters should be included in the docs of register_taxonomy()?

[birgire]

I think the comment ticket:42019#comment:9 by @johnbillion, is a good guideline:

[...] the approach that only parameters which are specific to that function, or which have a default value different to the default in the descendant function, should be documented. This removes repetition in the documentation.

and also the reply ticket:42019#comment:7 by @SergeyBiryukov

So you want the docs of register_taxonomy() to be more like get_posts().

yes, e.g. how the @see is used, but I don't see any specific $args parameters used in register_taxonomy().

Do you have a suggestion on what some of the parameters should be included in the docs of register_taxonomy()?

What about swapping the $args description between the WP_Taxonomy::set_props() docblock and the register_taxonomy() docblock? Or it looks like the $args description from WP_Taxonomy::__construct() is more suitable for the register_taxonomy() docblock?

[stevenlinx]

saved the doc changes for set_props()