Docblock improvements for WP 5.8

[SergeyBiryukov]

Previously:

• #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)

[SergeyBiryukov]

In 50434:

Docs: Correct function name in add_settings_field() DocBlock.

See #52628.

[SergeyBiryukov]

In 50460:

Docs: Clarify a comment about wp_opcache_invalidate() in _copy_dir().

Follow-up to [48160].

See #52628.

[SergeyBiryukov]

In 50484:

Docs: Update documentation in some WP_REST_Request tests per the documentation standards.

Follow-up to [49329].

See #52628.

[SergeyBiryukov]

In 50491:

Docs: Update inline comments in some test files per the documentation standards.

See #52628.

[johnbillion]

In 50505:

Docs: Add examples of possible names for various hooks whose name contains a dynamic portion.

This provides greater discoverability of such hooks in search results on the Code Reference site as well as increased clarity when reading the source.

See #50734, #52628

[peterwilsoncc]

In 50516:

Docs: Improve compatibility comment in WP_List_Table.

Improve comment explaining backward compatibility check for the primary column in WP_List_Table::get_column_info().

Unprops helen, markjaquith.
See #52628, #34564.

[jeremyfelt]

Replying to peterwilsoncc:

In 50516:

"added as a forth item" should be "added as a fourth item" :)

[peterwilsoncc]

In 50517:

Docs: Improve spelling in [50516].

Props jeremyfelt.
See #52628, #34564.

[SergeyBiryukov]

In 50531:

Docs: Correct DocBlock formatting for register_block_style_handle().

Follow-up to [48141].

See #52628.

[SergeyBiryukov]

In 50532:

Docs: Synchronize $category_name description in WP_Block_Pattern_Categories_Registry methods.

Follow-up to [48156].

See #52628.

[SergeyBiryukov]

In 50562:

Docs: Fix typo in pre_term_link filter description.

See #52628.

[sabernhardt]

52628.htmlhint.diff​ corrects docblock from r41558

[davidbaumwald]

Thanks for the patch, @sabernhardt. I found another instance of $htmlhint being improperly described in another docblock on line 3537 in wp-includes/general-template.php. I'll address that one as well in the commit that follows.

[davidbaumwald]

In 50583:

Docs: Fix description for $htmlhint argument in code editor settings.

Introduced in [41558].

Props sabernhardt.
See #52628.

[SergeyBiryukov]

In 50610:

Docs: Spell "non-existent" in a consistent way.

See #52628.

[SergeyBiryukov]

In 50781:

Docs: Add a @since note to wp_mail() about using is_email() for validation.

Follow-up to [48645].

See #52628.

[ocean90]

[49597] has limited the return type of wp_get_object_terms() to only arrays of type WP_Term. But depending on the fields argument other array types are supported too. For example int[] in case of 'fields' => 'ids'. Same for the filters in the function.

[alexstine]

Added 52628.class-walker-page.diff to fix an incorrect comment from #43522 (r42808).

[SergeyBiryukov]

In 50823:

Docs: Correct the aria-current array key in the documentation for two widget filters.

This applies to nav_menu_link_attributes and page_menu_link_attributes filters.

Follow-up to [42808], [44416].

Props jnylen0, chetan200891, alexstine.
See #43522, #52628.

[johnbillion]

In 50828:

Docs: Miscellaneous docblock updates.

See #52628

This was skipped in the review for https://core.trac.wordpress.org/changeset/48315
A simple typo.

PS: I don't know how to handle this. I have reported this to https://core.trac.wordpress.org/ticket/52628

[laurencebahiirwa]

This was skipped in the review for https://core.trac.wordpress.org/changeset/48315

A simple typo. I have made a PR via ​https://github.com/WordPress/wordpress-develop/pull/1242. I do not know if that's the right space.

[SergeyBiryukov]

In 50831:

Docs: Correct @since tags for new properties and functions related to infinite scrolling in Media Library.

Follow-up to [50829].

See #50105, #40330, #52628.

[SergeyBiryukov]

In 50912:

Docs: Clarify the @since note for unlink-homepage-logo in get_custom_logo().

This should make it clearer that the value applies to the custom-logo theme feature.

Follow-up to [48039], [48283], [48749], [48757], [48758], [48832].

Props joyously.
See #51075, #52628.

[SergeyBiryukov]

In 50913:

Docs: Update documentation in phpunit/includes/abstract-testcase.php per the documentation standards.

Follow-up to [44902].

See #52628.

[SergeyBiryukov]

In 50916:

Docs: Miscellaneous DocBlock corrections.

See #52628.

[SergeyBiryukov]

In 50918:

Docs: Update documentation in wp-config-sample.php per the documentation standards.

See #52628.

[SergeyBiryukov]

In 50952:

Docs: Use 3-digit, x.x.x-style semantic versioning for two _doing_it_wrong() calls.

Follow-up to [37985], [38420], [39021].

See #52628.

[SergeyBiryukov]

In 51055:

Docs: Add a @since note to wp_parse_id_list() and wp_parse_slug_list() about using wp_parse_list().

Follow-up to [44546], [49941].

Props joyously, dlh, pbiron.
See #52628.

[SergeyBiryukov]

In 51138:

Docs: Correct DocBlock formatting for some revision tests.

Follow-up to [50949], [51124].

See #52628.

[SergeyBiryukov]

In 51142:

Docs: Update documentation for some WP_Customize_Widgets methods per the documentation standards.

• Add missing @since tags for the $id_base parameter of ::sanitize_widget_instance() and ::sanitize_widget_js_instance()`.
• Document the usage of $wp_widget_factory global in ::sanitize_widget_instance().
• Use multi-line comment syntax for a comment in ::enqueue_scripts().

Follow-up to [50996], [51141].

See #52628.

[desrosj]

Opened #53399 for the 5.9 cycle.

[SergeyBiryukov]

In 51150:

Docs: Document the usage of $_wp_current_template_content global in a few block template functions.

Follow-up to [51003], [51149].

See #52628.

[SergeyBiryukov]

In 51151:

Docs: Document the usage of $wp_embed global in WP_oEmbed_Controller::get_proxy_item().

Follow-up to [48135].

Fixes #52628.

[SergeyBiryukov]

In 51152:

Docs: Document the VALID_ORIGINS constant in WP_Theme_JSON.

Follow-up to [51149].

See #52628.

[SergeyBiryukov]

In 51157:

I18N: Use consistent pattern for placeholder references in translator comments for some bundled theme strings.

Follow-up to [42827], [44562], [50234].

See #52628.

[SergeyBiryukov]

In 51159:

Docs: Add missing documentation for wp_migrate_old_typography_shape().

Follow-up to [51089].

See #52991, #52628.

[SergeyBiryukov]

In 51168:

Docs: Update syntax for some multi-line comments per the documentation standards.

Follow-up to [51003], [51149].

See #52628.

[SergeyBiryukov]

In 51185:

Docs: Correct DocBlock formatting for Core_Upgrader::upgrade().

Document the $auto_update_settings parameter of the after_core_auto_updates_settings action.

Follow-up to [49254].

See #52628.

[SergeyBiryukov]

In 51188:

Docs: Correct @since version in the wp-includes/version.php file header.

There was no public release of WordPress 1.1.

Follow-up to [803], [43662].

See #52628.

[SergeyBiryukov]

In 51279:

Docs: Document the globals used in WP_REST_Widget_Types_Controller and WP_REST_Widgets_Controller.

Follow-up to [50995].

See #52628, #53461.

[SergeyBiryukov]

In 51280:

Docs: Add missing @since tags for some REST API methods added in 5.8.

Follow-up to [50995], [51021].

See #52628, #53461.

[SergeyBiryukov]

In 51281:

Docs: Add @ticket references to some WP_Theme_JSON tests.

Follow-up to [50973], [51054].

See #52628, #53461.

[SergeyBiryukov]

In 51282:

Docs: Adjust wp_dashboard_browser_nag() DocBlock per the documentation standards.

Follow-up to [51117], [51119], [51120].

See #52628, #53461.

[SergeyBiryukov]

In 51283:

Docs: Add missing @since tags for some WP_Theme_JSON methods.

Docs: Update syntax for multi-line comments per the documentation standards.

Follow-up to [50959], [50967], [50973], [51051], [51089], [51149].

See #52628, #53461.

[SergeyBiryukov]

In 51284:

Docs: Improve documentation for optional parameters in WP_Theme_JSON_Resolver methods per the documentation standards.

Move add_action() call to wp-includes/default-filters.php.

Follow-up to [50959], [51221].

See #52628, #53461.

[SergeyBiryukov]

In 51286:

Docs: List the expected type first instead of WP_Error in some REST API methods added in 5.8.

Follow-up to [46696], [49929], [50995], [51021].

See #52628, #53461.

[SergeyBiryukov]

In 51289:

Docs: Remove an empty line between @param and @return tags in some newly added REST API methods, per the documentation standards.

Follow-up to [48242], [49925], [51003], [51021].

See #52628, #53461.

[SergeyBiryukov]

In 51292:

Docs: Improve documentation for optional parameters in WP_Theme_JSON methods per the documentation standards.

Additionally:

• Remove an empty line between @param and @return tags.
• Correct alignment of @param tags.

Follow-up to [50959], [50973], [51149], [51284], [51289].

See #52628, #53461.

[SergeyBiryukov]

In 51294:

Twenty Twenty-One: Improve documentation per the documentation standards:

• Remove unnecessary @access tags that were previously removed from core.
• Remove an empty line between @param and @return tags.
• Correct alignment of @param tags.

Follow-up to [41161], [41162], [41168], [49216], [49220].

See #52628, #53461.

[SergeyBiryukov]

In 51304:

Twenty Twenty-One: Add missing documentation for some filters.

Add missing @since tags for some functions.

Follow-up to [49216], [49220], [49854], [51294].

See #52628, #53461.

[desrosj]

Reopening to backport.

[desrosj]

In 51310:

Docs: Document the globals used in WP_REST_Widget_Types_Controller and WP_REST_Widgets_Controller.

Follow-up to [50995].

Props SergeyBiryukov.
Merges [51279] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51311:

Docs: Add missing @since tags for some REST API methods added in 5.8.

Follow-up to [50995], [51021].

Props SergeyBiryukov.
Merges [51280] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51312:

Docs: Add @ticket references to some WP_Theme_JSON tests.

Follow-up to [50973], [51054].

Props SergeyBiryukov.
Merges [51280] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51313:

Docs: Adjust wp_dashboard_browser_nag() DocBlock per the documentation standards.

Follow-up to [51117], [51119], [51120].

Props SergeyBiryukov.
Merges [51282] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51314:

Docs: Add missing @since tags for some WP_Theme_JSON methods.

Docs: Update syntax for multi-line comments per the documentation standards.

Follow-up to [50959], [50967], [50973], [51051], [51089], [51149].

Props SergeyBiryukov.
Merges [51283] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51315:

Docs: Improve documentation for optional parameters in WP_Theme_JSON_Resolver methods per the documentation standards.

Move add_action() call to wp-includes/default-filters.php.

Follow-up to [50959], [51221].

Props SergeyBiryukov.
Merges [51284] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51316:

Docs: List the expected type first instead of WP_Error in some REST API methods added in 5.8.

Follow-up to [46696], [49929], [50995], [51021].

Props SergeyBiryukov.
Merges [51286] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51317:

Docs: Remove an empty line between @param and @return tags in some newly added REST API methods, per the documentation standards.

Follow-up to [48242], [49925], [51003], [51021].

Props SergeyBiryukov.
Merges [51289] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51318:

Docs: Improve documentation for optional parameters in WP_Theme_JSON methods per the documentation standards.

Additionally:

• Remove an empty line between @param and @return tags.
• Correct alignment of @param tags.

Follow-up to [50959], [50973], [51149], [51284], [51289].

Props SergeyBiryukov.
Merges [51292] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51319:

Twenty Twenty-One: Improve documentation per the documentation standards:

• Remove unnecessary @access tags that were previously removed from core.
• Remove an empty line between @param and @return tags.
• Correct alignment of @param tags.

Follow-up to [41161], [41162], [41168], [49216], [49220].

Props SergeyBiryukov.
Merges [51294] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51320:

Twenty Twenty-One: Add missing documentation for some filters.

Add missing @since tags for some functions.

Follow-up to [49216], [49220], [49854], [51294].

Props SergeyBiryukov.
Merges [51304] to the 5.8 branch.
See #52628, #53461.

[desrosj]

All changes have been backported. If more are needed, we can reopen to backport those.

[SergeyBiryukov]

In 51322:

Twenty Twenty: Add missing documentation for some filters.

Add missing @since tags for some functions.

Correct alignment of some @param tags.

Follow-up to [46271], [46278], [51304].

See #52628, #53461.

[SergeyBiryukov]

In 51323:

Bundled Themes: Correct @since tags for block patterns.

Follow-up to [49347], [49348], [49583], [49584], [49763], [51103].

See #52628, #53461.

[SergeyBiryukov]

In 51324:

Docs: Correct @see references for hooks in the get_option() description.

Follow-up to [51050].

See #52628, #53461.

[desrosj]

In 51338:

Twenty Twenty: Add missing documentation for some filters.

Add missing @since tags for some functions.

Correct alignment of some @param tags.

Follow-up to [46271], [46278], [51304].

Props SergeyBiryukov.
Merges [51322] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51339:

Bundled Themes: Correct @since tags for block patterns.

Follow-up to [49347], [49348], [49583], [49584], [49763], [51103].

Props SergeyBiryukov.
Merges [51324] to the 5.8 branch.
See #52628, #53461.

[desrosj]

In 51340:

Docs: Correct @see references for hooks in the get_option() description.

Follow-up to [51050].

Props SergeyBiryukov.
Merges [51324] to the 5.8 branch.
See #52628, #53461.

Thanks for the PR! This was merged in r53251.