WordPress.org

Make WordPress Core

Opened 2 years ago

Last modified 2 years ago

#42253 new enhancement

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

Reported by: birgire Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: 4.7
Component: Taxonomy Keywords: has-patch
Focuses: docs Cc:

Description

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

Attachments (2)

42253.diff (7.7 KB) - added by stevenlinx 2 years ago.
42253.2.diff (13.7 KB) - added by stevenlinx 2 years ago.
saved the doc changes for set_props()

Download all attachments as: .zip

Change History (6)

#1 @birgire
2 years ago

  • Keywords needs-patch added

Related #25150 (also #42156 and #42117)

Good-first-bug?

#2 @stevenlinx
2 years ago

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()?

#3 @birgire
2 years ago

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
2 years ago

#4 @stevenlinx
2 years ago

  • Keywords has-patch added; needs-patch removed

@stevenlinx
2 years ago

saved the doc changes for set_props()

Note: See TracTickets for help on using tickets.