WordPress.org

Make WordPress Core

Opened 3 weeks ago

Last modified 9 days ago

#42019 reviewing task (blessed)

Auto-generated reference for wp_tag_cloud() doesn't match its current state

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

Description

On

https://developer.wordpress.org/reference/functions/wp_tag_cloud/

the reference to wp_tag_cloud()'s arguments and behavior doesn't match that of wp_generate_tag_cloud() (where it is up-to-date)

The mentioned wp_tag_cloud() reference page misinforms developer about actual function's arguments and behavior, as of version 4.8.0. Since the reference page is auto-generated from source, the corresponding comment block above function body in /wp-includes/category-template.php should be updated as well.

Attachments (2)

42019.patch (3.7 KB) - added by birgire 3 weeks ago.
42019.2.patch (3.5 KB) - added by johnbillion 2 weeks ago.

Download all attachments as: .zip

Change History (13)

@birgire
3 weeks ago

#1 @birgire
3 weeks ago

  • Focuses docs added
  • Keywords has-patch added

Thanks for reporting it @temmokan

42019.patch adds inline documentation for the default arguments of wp_tag_cloud(), based e.g. on inline docs for wp_generate_tag_cloud(), get_terms() and get_edit_term_link().

#2 @johnbillion
3 weeks ago

  • Component changed from General to Taxonomy
  • Milestone changed from Awaiting Review to 4.9
  • Owner set to johnbillion
  • Status changed from new to reviewing

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


2 weeks ago

#4 @johnbillion
2 weeks ago

  • Keywords commit added
  • Version 4.8.2 deleted

#5 @johnbillion
2 weeks ago

  • Keywords commit removed

Actually this needs some tweaks. I'm working on it.

#6 @johnbillion
2 weeks ago

  • Type changed from enhancement to task (blessed)

@johnbillion
2 weeks ago

#7 follow-up: @johnbillion
2 weeks ago

42019.2.patch takes 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.

Thoughts from the docs team?

This ticket was mentioned in Slack in #core-docs by johnbillion. View the logs.


2 weeks ago

#9 in reply to: ↑ 7 @SergeyBiryukov
13 days ago

Replying to johnbillion:

Thoughts from the docs team?

From @DrewAPicture in comment:9:ticket:41058:

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.

#10 follow-up: @temmokan
10 days ago

How will the resulted auto-generated documentation look like?

It would be nice to give the exact links to corresponding two functions wrapped by this one (I suppose the same approach would be useful for other wrappers).

Thanks.

#11 in reply to: ↑ 10 @DrewAPicture
9 days ago

Replying to temmokan:

How will the resulted auto-generated documentation look like?

It would be nice to give the exact links to corresponding two functions wrapped by this one (I suppose the same approach would be useful for other wrappers).

Thanks.

We're working on getting top-level @see tags displayed in code reference articles via #meta3165, so that would be the preferred method for cross-referencing functions via the docs.

In terms of how it would look, every argument that is actually documented in the hash notation would be listed out in a bulleted list.

Note: See TracTickets for help on using tickets.