[wp-trac] [WordPress Trac] #42253: Adjust the inline docs for register_taxonomy() and WP_Taxonomy::set_props()

[WordPress Trac]

#42253: Adjust the inline docs for register_taxonomy() and WP_Taxonomy::set_props()
-------------------------+------------------------------
 Reporter:  birgire      |       Owner:
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Taxonomy     |     Version:  4.7
 Severity:  normal       |  Resolution:
 Keywords:  needs-patch  |     Focuses:  docs
-------------------------+------------------------------

Comment (by 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?

--
Ticket URL: <https://core.trac.wordpress.org/ticket/42253#comment:3>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform