WordPress.org

Make WordPress Core

Opened 3 months ago

Last modified 4 weeks 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: 5.0 Priority: normal
Severity: normal Version:
Component: Taxonomy Keywords: has-patch 2nd-opinion
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 months ago.
42019.2.patch (3.5 KB) - added by johnbillion 2 months ago.

Download all attachments as: .zip

Change History (16)

@birgire
3 months ago

#1 @birgire
3 months 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 months 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 months ago

#4 @johnbillion
2 months ago

  • Keywords commit added
  • Version 4.8.2 deleted

#5 @johnbillion
2 months ago

  • Keywords commit removed

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

#6 @johnbillion
2 months ago

  • Type changed from enhancement to task (blessed)

#7 follow-up: @johnbillion
2 months 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 months ago

#9 in reply to: ↑ 7 @SergeyBiryukov
2 months 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
2 months 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
2 months 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.

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


8 weeks ago

#13 @johnbillion
8 weeks ago

  • Keywords 2nd-opinion added
  • Milestone changed from 4.9 to 5.0

#14 @birgire
4 weeks ago

#42650 was marked as a duplicate.

Note: See TracTickets for help on using tickets.