Docblock improvements for WP 5.7

[SergeyBiryukov]

Previously:

• #50768 (5.6)
• #49572 (5.5)
• #48303 (5.4)
• #47110 (5.3)
• #46543 (5.2)
• #42505 (5.1)
• #41017 (4.9)
• #39130 (4.8)
• #37770 (4.7)
• #32246 (4.6)

[johnbillion]

In 49670:

Docs: Clarify and standardise on terminology used for rewrite rule endpoint masks.

See #51800

[johnbillion]

In 49671:

Docs: Add missing @since tags.

See #51800

[johnbillion]

In 49672:

Docs: Document parameters that accept an array of integers using typed array notation.

While many of these parameters also technically accept an array of numerical strings, they are all ultimately cast to an array of integers. Documenting them as such assists developers in understanding the expected types.

See #51800, #41756

[SergeyBiryukov]

In 49675:

Docs: Add missing @since tags for WP_Upgrader_Skin methods.

See #51800.

[SergeyBiryukov]

In 49678:

Docs: Correct @since tag for the class-wp-widget-area-customize-control.php file.

Per the documentation standards, the file header @since tag is supposed to specify when the file was introduced.

Follow-up to [35389].

See #51800.

[SergeyBiryukov]

In 49688:

Docs: Clarify that the $class argument of wp_list_bookmarks() can accept an array.

Follow-up to [32906].

See #51855, #51800.

[johnbillion]

In 49692:

Docs: Various docblock corrections relating to parameter types.

See #51800

[johnbillion]

In 49693:

Docs: Upgrade more parameters in docblocks to used typed array notation.

See #51800, #41756

[SergeyBiryukov]

In 49698:

Docs: Use typed array notation for the $size parameter of embed_defaults filter.

Previously committed in [42876], accidentally reverted in [44154].

See #51800.

[johnbillion]

In 49700:

Docs: Corrections and improvements to docs for properties of the WP_Query class.

This also adds additional type hinting inside some methods to help IDEs.

See #51800

[SergeyBiryukov]

In 49735:

Docs: Clarify the $format parameter description in comment_time().

See #51800.

[peterwilsoncc]

In 49758:

Docs, Tests: Correctly capitalize JavaScript.

Correct Javascript to JavaScript within Wordpress core ;)

See #51800, #51802.

[SergeyBiryukov]

In 49769:

Docs: Fix typo in references to WP_Error in some DocBlocks.

See #51800.

[SergeyBiryukov]

In 49785:

Docs: Fix typo in some DocBlocks.

See #51800.

[johnbillion]

In 49787:

Docs: Fix some docblock issues introduced in 5.6.

See #51800

[johnbillion]

In 49788:

Upgrade/Install: Remove a duplicate description for the upgrader_overwrote_package action.

See #51800, #9757

[johnbillion]

In 49789:

Docs: Various docblock corrections.

See #51800

[johnbillion]

In 49790:

Docs: Various docblock improvements.

See #51800

[johnbillion]

In 49802:

Docs: Correct the documentation for the map_meta_cap() function and its filter.

See #51800

[SergeyBiryukov]

In 49837:

Docs: Update the reference to Appearance → Theme Editor admin menu item in the inline documentation.

Follow-up to [42685].

See #51800.

[SergeyBiryukov]

In 49858:

Docs: Move sanitize_file_name filter documentation to the canonical place.

See #51800.

[SergeyBiryukov]

In 49859:

Docs: Move locale filter documentation to the canonical place.

See #51800.

[johnbillion]

In 49926:

Docs: Various docblock corrections particularly relating to boolean types.

See #51800

[johnbillion]

In 49927:

Docs: Promote many bool types to true or false where only that value is used.

See #51800

[SergeyBiryukov]

@johnbillion It looks like [49926] reverts string|string[] back to string|array for wp_unslash(), but not for wp_slash(), essentially reverting [47400], but keeping [48441]. Is that intentional?

[SergeyBiryukov]

In 49928:

Docs: Synchronize and correct documentation for has_filter() and WP_Hook::has_filter().

WP_Hook::has_filter() returns true if $function_to_check is omitted and the hook being checked has one or more registered callbacks.

Follow-up to [49927].

See #51800.

[johnbillion]

@SergeyBiryukov Thanks. This was an intentional change because the array returned by wp_unslash() is not always an array of strings, for example when unslashing an array of arrays. I'll do a follow-up.

[SergeyBiryukov]

In 49929:

Docs: In various @return tags, list the expected type first, instead of false or WP_Error.

Follow-up to [46696], [47060], [49926], [49927].

See #51800.

[johnbillion]

@SergeyBiryukov Does 51800.diff​ look ok?

[SergeyBiryukov]

Replying to johnbillion:

Does 51800.diff​ look ok?

Yes, looks good to me :) Thanks!

[SergeyBiryukov]

In 49934:

Docs: Fix typo in wp_set_comment_status filter DocBlock.

Follow-up to [49926].

See #51800.

[SergeyBiryukov]

In 49935:

Docs: Use more consistent descriptions for void|false return values.

See #51800.

[johnbillion]

In 49936:

Docs: Corrections and improvements to types used in various docblocks.

See #51800, #52217

[SergeyBiryukov]

In 49941:

Docs: Correct description for wp_parse_list().

The function simply converts a comma- or space-separated list of scalar values to an array and does not perform any sanitization on its own.

Follow-up to [44546].

Props johnjamesjacoby.
See #51800.

[johnbillion]

In 49942:

Docs: Miscellaneous docblock corrections and improvements.

See #51800.

[johnbillion]

In 49946:

Plugins: Replace usage of $this in action and filter parameter docblocks with more appropriate variable names.

See #51800, #52217

Fixes #52243

[johnbillion]

In 49947:

Taxonomy: Correct and clarify documentation for the return types of term query functions.

See #51800, #38266

[johnbillion]

In 49955:

REST API: Corrections and improvements to docblocks for REST API filters.

See #51800

[SergeyBiryukov]

In 49963:

Docs: In various @return tags, list the expected type first, instead of false.

Follow-up to [46696], [47060], [49926], [49927], [49929].

See #51800.

[SergeyBiryukov]

In 49965:

Coding Standards: Fix WPCS issue in [49963].

Props pawki07, mukesh27.
Fixes #52316. See #51800.

[SergeyBiryukov]

In 49968:

Docs: Correct description for wp_slash() and wp_unslash().

The array received or returned by these functions is not always an array of strings, for example when slashing or unslashing an array of arrays.

Follow-up to [47400], [48441], [49926].

Props johnbillion.
See #51800.

[SergeyBiryukov]

In 49977:

Docs: Link to the parent function for accepted arguments in some filters for HTML output.

See #51800.

[SergeyBiryukov]

In 50122:

Docs: Add @since notes for some of the recently introduced meta capabilities.

Follow-up to [42832], [43085], [43147], [43155], [43381], [44973], [50114].

See #51800.

[SergeyBiryukov]

In 50138:

Docs: Add a @since note to map_meta_cap() for the update_https capability.

Follow-up to [50122], [50131].

See #51800.

[SergeyBiryukov]

In 50175:

Docs: Consistently document the default value for $args parameter in various cron functions.

See #51800.

[SergeyBiryukov]

In 50233:

Twenty Twenty-One: Capitalize translator comments consistently.

Follow-up to [45932].

See #51800.

[SergeyBiryukov]

In 50234:

I18N: Use the actual placeholder instead of a number in translator comments if the corresponding string does not use numbered placeholders.

Adjust some newly introduced strings to remove unnecessary numbered placeholders for consistency.

Follow-up to [42827].

See #51800.

[peterwilsoncc]

In 50257:

Posts/Post Types: Improve documentation of get_posts().

Add references to WP_Query to the documentation of get_posts(). As the developer documentation for WP_Query includes an expanded explanation a full link to developer.wordpress.org is included rather than a standard @see.

Props dam6pl, peterwilsoncc.
See #51852, #51800.

[SergeyBiryukov]

In 50264:

Docs: Update some recently added inline comments per the documentation standards.

Follow-up to [50256], [50258], [50259].

See #51800.

[ocean90]

In 50340:

Docs: Improve parameter types for various URL functions and filters that also accept null.

See #51800.

[SergeyBiryukov]

In 50372:

Docs: Correct the type of $widget_id argument in is_active_widget().

See #51800.

[SergeyBiryukov]

In 50373:

Docs: Correct the alternative hook name for the deprecated whitelist_options hook.

Follow-up to [48121].

See #51800.

[johnbillion]

In 50395:

Docs: Various docblock corrections and improvements.

See #51800

[SergeyBiryukov]

In 50407:

Docs: Document the usage of $pagenow global in a few functions.

See #51800.

[SergeyBiryukov]

Follow-up: #52628