WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 3 years ago

Last modified 2 years ago

#42019 closed task (blessed) (fixed)

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

Reported by: temmokan Owned by: johnbillion
Milestone: 5.1 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 years ago.
42019.2.patch (3.5 KB) - added by johnbillion 3 years ago.

Download all attachments as: .zip

Change History (18)

@birgire
3 years ago

#1 @birgire
3 years 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 years 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.


3 years ago

#4 @johnbillion
3 years ago

  • Keywords commit added
  • Version 4.8.2 deleted

#5 @johnbillion
3 years ago

  • Keywords commit removed

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

#6 @johnbillion
3 years ago

  • Type changed from enhancement to task (blessed)

@johnbillion
3 years ago

#7 follow-up: @johnbillion
3 years 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.


3 years ago

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


3 years ago

#13 @johnbillion
3 years ago

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

#14 @birgire
3 years ago

#42650 was marked as a duplicate.

#15 @DrewAPicture
3 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

In 42658:

Docs: Document default arguments for wp_tag_cloud() in a hash notation, noting that full lists of additionally-supported arguments are already documented in get_terms() and wp_generate_tag_cloud().

Props birgire, johnbillion.
Fixes #42019.

#16 @johnbillion
2 years ago

  • Milestone changed from 5.0 to 5.1
Note: See TracTickets for help on using tickets.