Docblock improvements for WP 6.0

[hellofromTonya]

Previously:

• #53399 (5.9)
• #52628 (5.8)
• #51800 (5.7)
• #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)

Typos in misc. docblocks.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

[audrasjb]

Self assigning PR2173 for commit. Thanks @kebbet 🙌

[audrasjb]

In 52582:

Docs: Miscellaneous docblock corrections in REST API and Sitemaps API.

Props kebbet.
See #54729.

Committed in https://core.trac.wordpress.org/changeset/52582

Typos in misc. docblocks.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

The two reverted changes are reported upstream in ​https://github.com/WordPress/gutenberg/pull/38048

[SergeyBiryukov]

In 52597:

Docs: Fix typos in some DocBlocks.

Props kebbet.
See #54729.

Thanks for the PR! Merged in https://core.trac.wordpress.org/changeset/52597.

[johnbillion]

In 52652:

Docs: Increase the specificity of types in various inline documentation.

See #54729

Use correct function name in DocBlock for wp_kses_attr.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

[audrasjb]

In 52680:

Docs: Typo corrections in various API docblocks.

Props hasanuzzamanshamim.
Fixes #55073.
See #54729.

Spell overridden with two d's
https://core.trac.wordpress.org/ticket/54729

[audrasjb]

In 52692:

Docs: Typo correction in class-wp-theme-json docblocks.

Props kebbet.
See #54729.

Committed in https://core.trac.wordpress.org/changeset/52692

[audrasjb]

In 52693:

Docs: Fix an error in wp_kses_attr() docblock.

Props kebbet.
See #54729.

Committed in https://core.trac.wordpress.org/changeset/52693

[SergeyBiryukov]

In 52703:

Docs: Update DocBlocks for some object cache functions per the documentation standards.

Follow-up to [47060], [47938], [47944], [52700].

See #54729, #54574.

[SergeyBiryukov]

In 52704:

Docs: Correct @since tag for wp_cache_reset().

The function was added in WordPress 3.0, not 2.6.

Follow-up to [13066].

See #54729.

[SergeyBiryukov]

In 52705:

Docs: Correct the suggested alternative for the deprecated wp_cache_reset() function.

While this was previously added and reverted more than once as part of various documentation cleanup efforts, wp_cache_switch_to_blog() appears to be the correct alternative for wp_cache_reset(), per the latter's DocBlock.

This commit also corrects the @deprecated tag for WP_Object_Cache::reset() to link to the ::switch_to_blog() method of the class, instead of the function of the same name.

Follow-up to [13066], [21403], [22111], [33678], [34225], [34226], [40929].

See #54729.

[SergeyBiryukov]

In 52708:

Docs: Improve @return tags for wp_cache_*_multiple() functions:

• wp_cache_add_multiple()
• wp_cache_set_multiple()
• wp_cache_get_multiple()
• wp_cache_delete_multiple()

This aims to provide more details about the returned value types.

Follow-up to [52700], [52702], [52703].

See #54729, #54574.

[hellofromTonya]

Replying to audrasjb:

In 52692:

Docs: Typo correction in class-wp-theme-json docblocks.

Props kebbet.
See #54729.

To resolve a backport conflict for 5.9.1 (in backporting [52757] to 5.9 branch), marking r52692 as reviewed and approved for backport to 5.9 branch. In doing this additional backport, the changeset 1:1 relationship is retained.

[audrasjb]

In 52758:

Docs: Typo corrections in class-wp-theme-json docblocks.

Props kebbet, hellofromtonya.
Merges [52692] to the 5.9 branch.
See #54729.

[hellofromTonya]

Resetting the keywords after r52758.

[SergeyBiryukov]

In 52776:

Docs: Improve some DocBlocks in wp_validate_boolean() tests for consistency.

Follow-up to [46159], [46224], [52775].

See #54725, #54729.

[SergeyBiryukov]

In 52777:

Docs: Correct parameter types for data_wp_validate_boolean().

Follow-up to [46159], [46224], [52775], [52776].

See #54725, #54729.

[SergeyBiryukov]

In 52779:

Docs: Fix typo in TracTickets::isTracTicketClosed() description.

Follow-up to [761/tests], [762/tests], [891/tests].

See #54729.

[audrasjb]

In 52793:

Docs: Correct return type for get_block_metadata_i18n_schema().

Props jeremyfelt.
Fixes #55243.
See #54729.

[audrasjb]

In 52795:

Docs: Correct return type for get_post_custom().

Props chouby, audrasjb.
Fixes #55249.
See #54729.

[SergeyBiryukov]

In 52810:

Docs: Use third-person singular verbs for function descriptions in wp-includes/formatting.php, per the documentation standards.

See #54729.

[SergeyBiryukov]

In 52821:

Docs: Add inline comments for non-visible characters in sanitize_title_with_dashes().

This aims to clarify the list of characters that are stripped from URLs or converted to a hyphen.

Follow-up to [51984].

See #47912, #54729.

[azouamauriac]

in src/wp-includes/class-wp-user.php use third person in function docblock

Trac ticket: https://core.trac.wordpress.org/ticket/54729

[audrasjb]

Thanks @azouamauriac, I'll commit this patch right now 👍

Committed in https://core.trac.wordpress.org/changeset/52826

[audrasjb]

In 52827:

Docs: Use third-person singular verbs for function descriptions in wp-includes/class-wp-user.php.

Props azouamauriac.
See #54729.

[audrasjb]

In 52930:

Docs: Use third-person singular verbs for function descriptions in wp-includes/class-wp-locale.php.

Follow-up to [52929].

See #54729.

[audrasjb]

In 52931:

Docs: Miscellaneous fixes in wp-admin/includes/plugin-install.php and wp-admin/includes/plugin.php.

See #54729.

[SergeyBiryukov]

In 52934:

Docs: Further clarify the description for install_dashboard().

Follow-up to [52931].

See #54729.

[azouamauriac]

in src/wp-includes/post-template.php and src/wp-includes/post-thumbnail-template.php use third person in function docblock

[audrasjb]

Thanks @azouamauriac, self assigning 54729.2.diff for review/commit.

[azouamauriac]

Replying to audrasjb:

Thanks @azouamauriac, self assigning 54729.2.diff for review/commit.

Thanks.👍

[audrasjb]

In 52935:

Docs: Misc. fixes in wp-includes/post-template.php and wp-includes/post-thumbnail-template.php.

Props azouamauriac, audrasjb.
See #54729.

[SergeyBiryukov]

In 52941:

Docs: Add a @since note about Twenty Twenty-Two for WP_Theme::$default_themes.

Follow-up to [51328], [52093].

See #54729.

[peterwilsoncc]

In 52943:

Editor/Docs: Add blockTypes argument to WP_Block_Patterns_Registry::register() docblock.

Add the optional blockTypes argument in the patten properties for WP_Block_Patterns_Registry::register().

Props vlad.olaru.
Fixes #55303.
See #54729.

[SergeyBiryukov]

In 52959:

Docs: Correct variable references in get_category_feed_link() and get_term_feed_link() @return tags.

The $cat_id and $term_id variables were replaced by $cat and $term, respectively.

Follow-up to [52180].

See #54729.

[SergeyBiryukov]

In 52984:

Docs: Adjust documentation in get_post_galleries() tests per the documentation standards.

Follow-up to [52190], [52797].

Props azouamauriac, SergeyBiryukov.
See #54725, #54729.

[SergeyBiryukov]

In 52992:

Docs: Use third-person singular verbs for function descriptions in wp-includes/taxonomy.php, per the documentation standards.

See #54729.

[audrasjb]

In 52994:

Docs: Use third-person singular verbs for function descriptions in wp-includes/rewrite.php, per the documentation standards.

See #54729.

[audrasjb]

In 52999:

Docs: Use third-person singular verbs for function descriptions in wp-includes/template.php, per the documentation standards.

See #54729.

[johnbillion]

In 53000:

Docs: Correct the documented return types for date and time related functions and filters.

See #54729

[audrasjb]

In 53002:

Docs: Use third-person singular verbs for function descriptions in wp-admin/includes/theme.php and wp-admin/includes/theme-install.php, per the documentation standards.

See #54729.

[costdev]

Related: #55493

[SergeyBiryukov]

In 53040:

Docs: Add missing descriptions for WP_List_Table::get_items_per_page() parameters.

Follow-up to [53039].

Props jrf, aristath, poena, justinahinon, SergeyBiryukov.
See #54729, #55327.

[azouamauriac]

Related: #55506

[audrasjb]

In 53046:

Docs: Use third-person singular verbs for function descriptions in WP_Embed class, per the documentation standards.

See #54729.

[azouamauriac]

Use third-person singular verbs for function descriptions in src/wp-includes/class-wp-customize-manager.php

[audrasjb]

In 53054:

Docs: Use third-person singular verbs for function descriptions in WP_Customize_Manager class, per the documentation standards.

Props azouamauriac.
See #54729.

[audrasjb]

In 53055:

Docs: Use third-person singular verbs for function descriptions in WP_Customize_Nav_Menus class, per the documentation standards.

Follow-up to [53054].

See #54729.

[SergeyBiryukov]

In 53056:

Docs: Use correct format for multi-line comments in the_block_editor_meta_boxes().

Follow-up to [44131], [44260].

See #54729.

[SergeyBiryukov]

In 53060:

Docs: Add missing description for $pagenow global in various functions.

See #54729, #55499.

[SergeyBiryukov]

In 53061:

Docs: Add missing description for $typenow global in various functions.

Follow-up to [53060].

See #54729.

[SergeyBiryukov]

In 53062:

Docs: Add missing description for $taxnow global in various functions.

Follow-up to [53060], [53061].

See #54729.

[audrasjb]

In 53064:

Docs: Use third-person singular verbs for function descriptions in WP_Automatic_Updater class, per the documentation standards.

See #54729.

[SergeyBiryukov]

In 53086:

Docs: Adjust some deprecated function DocBlocks per the ​documentation standards.

This ensures the replacement functions are linked correctly in the WordPress Code Reference.

Follow-up to [38515], [43548], [49992], [51348], [51586], [52757], [53082].

See #54729.

[SergeyBiryukov]

In 53087:

Docs: Adjust DocBlock formatting for wp_robots_*() and related functions.

This ensures the code blocks are displayed correctly in the WordPress Code Reference.

Follow-up to [19304], [37541], [44021], [49992].

See #54729.

[audrasjb]

In 53146:

Docs: Misc. docblock fixes in wp-admin/includes/mic.php, as per documentation standards.

See #54729.

[audrasjb]

In 53176:

Docs: Fix @link URLs in get_merged_data() Docblock.

This addresses some 404s found on Helphub links by replacing the related @link sources.

See #54729.

[audrasjb]

In 53177:

Docs: Small fixes in WP_Theme_JSON_Resolver docblocks, as per documentation standards.

See #54729.

[audrasjb]

In 53179:

Docs: Misc. Docblocks improvements in the Core User API.

See #54729.

[audrasjb]

In 53180:

Docs: Removes an irrelevant @link mention in Translation_Entry Class.

See #54729.

[audrasjb]

In 53189:

Docs: Use third-person singular verbs for function descriptions in author-template.php, as per documentation standards.

See #54729.

[SergeyBiryukov]

In 53194:

Docs: Add missing documentation for add_cssclass() and add_menu_classes().

Follow-up to [9578], [53193].

See #54729.

[SergeyBiryukov]

In 53200:

Docs: Add missing descriptions for function parameters in wp-admin/includes/meta-boxes.php.

See #54729.

[SergeyBiryukov]

In 53201:

Docs: Use third-person singular verbs for function descriptions in wp-admin/includes/meta-boxes.php, per the documentation standards.

See #54729.

[audrasjb]

In 53202:

Docs: Update MDN link in send_frame_options_header() docblock.

The X-Frame-Options MDN documentation has been moved to /docs/Web/HTTP/Headers/X-Frame-Options. This changeset updates the link accordingly.

See #54729.

[audrasjb]

In 53204:

Docs: Update a link to the Custom Elements spec in force_balance_tags() docblock.

This changeset replaces a link to the outdated W3C specs on Custom Elements with a link to the corresponding WhatWG specification.

See #54729.

[audrasjb]

In 53205:

Docs: Update a link to the Custom Elements spec in unsupported_valid_tag_names() unit test docblock.

This changeset replaces a link to the outdated W3C specs on Custom Elements with a link to the corresponding WhatWG specification.

Follow-up to [53204].

See #54729.

[audrasjb]

In 53206:

Docs: Replace Codex links with the corresponding page on DevHub.

The Codex page for WP_Object_Cache already redirects to the corresponding DevHub page.

See #54729.

[audrasjb]

In 53229:

Docs: Misc fixes and improvements in the Administration Media API docblocks, as per documentation standards.

See #54729.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

[audrasjb]

In 53235:

Docs: Docs: Use third-person singular verbs for function descriptions in wp-includes/blocks.php and wp-includes/script-loader.php, per the documentation standards.

See #54729.

[SergeyBiryukov]

In 53244:

Docs: Correct the expected parameter type for WP_Customize_Manager::remove_preview_signature().

Before the method was deprecated, the parameter contained the value passed through for the wp_die_handler filter, which expects a callable function.

Follow-up to [20926], [32535], [34320], [38810], [53242], [53243].

See #54729.

[audrasjb]

In 53248:

Docs: Use third-person singular verbs for function descriptions in Multisite WordPress API, as per docs standards.

See #54729.

[audrasjb]

In 53249:

Docs: Use third-person singular verbs for function descriptions in wp-includes/capabilities.php, as per docs standards.

Props azouamauriac.
See #54729.

Thanks, committed in https://core.trac.wordpress.org/changeset/53249

[audrasjb]

In 53250:

Docs: Use third-person singular verbs for function descriptions in wp-includes/ms-load.php, as per docs standards.

See #54729.

[audrasjb]

In 53251:

Docs: Typo correction in wp-includes/ms-functions.php docblock.

See #54729.

[audrasjb]

In 53252:

Docs: Use third-person singular verbs for function descriptions in wp-includes/nav-menu.php, as per docs standards.

See #54729.

[audrasjb]

In 53254:

Docs: Use third-person singular verbs for function descriptions in WP_Theme Class, as per docs standards.

See #54729.

[audrasjb]

In 53256:

Docs: Use third-person singular verbs for function descriptions in WP_User_Query Class, as per docs standards.

See #54729.

[audrasjb]

In 53265:

Docs: Use third-person singular verbs for function descriptions in Core Comment API and Comment template functions.

See #54729.

[SergeyBiryukov]

In 53279:

Docs: Correct alignment for the customize_nav_menu_available_items filter DocBlock.

Follow-up to [53245].

See #54729.

[SergeyBiryukov]

In 53280:

Docs: Add missing documentation for WP_*_Query::get_search_sql() method parameters.

Includes renaming the $cols parameter to $columns for consistency across the classes.

Follow-up to [42876], [53272-53276].

See #54729.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

[johnbillion]

In 53300:

Docs: Various docblock corrections.

See #54729

[johnbillion]

In 53301:

Mail: Improve the docblocks for actions and functions related to the parsing of authentication cookies.

See #54729

[johnbillion]

In 53302:

Docs: Various docblock corrections and improvements for changes introduced in 6.0.

See #54729

https://core.trac.wordpress.org/changeset/53302

[SergeyBiryukov]

In 53314:

Docs: Adjust comments in Gruntfile.js per the documentation standards.

See #54729.

[johnbillion]

In 53316:

Docs: Corrections and improvements to docblocks for function and hooks relating to fatal error handling.

See #54729

[johnbillion]

In 53317:

Docs: Formatting corrections for various docblocks.

See #54729

[johnbillion]

In 53318:

Docs: Improve documentation of the walker argument for various functions.

See #54729

[audrasjb]

In 53323:

Docs: Docblock adjustements in the Walker class.

This changeset ensures third-person singular verbs are used for function descriptions in the Walker class, and adjusts some non-standard docblock descriptions for various properties and methods of the class.

See #54729.

[audrasjb]

In 53324:

Docs: Clarify the name and description of some parameters in the Walker class.

Follow-up to [53323].
See #54729.

[costdev]

With 6.0 RC1 tomorrow, closing this ticket.

If there are any more changes required between now and the final 6.0 release, this can be referenced and reopened if necessary with dev-reviewed.

#55646 is open for continuation during the 6.1 cycle.

[SergeyBiryukov]

In 53331:

Docs: Remove @return void from various DocBlocks.

Per the documentation standards, it should not be used outside of the default bundled themes.

Follow-up to [38767], [47055], [49697], [50956], [51003], [52069], [53255].

See #54729.

[audrasjb]

In 53332:

Docs: Correct parameter types for serialize_block() and serialize_blocks().

This changeset clarifies the expected type for the first parameter passed to serialize_block() and serialize_blocks() functions.

Props manooweb.
Fixes #55648.
See #54729.