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

[temmokan]

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.

[birgire]

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

[johnbillion]

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

[johnbillion]

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?

[SergeyBiryukov]

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.

[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.

[DrewAPicture]

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.

[birgire]

#42650 was marked as a duplicate.

[DrewAPicture]

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.