Docblock improvements for 6.1

[costdev]

Previously:

• #54729 (6.0)
• #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)

[audrasjb]

In 53397:

Docs: Use third-person singular verbs for function descriptions in the WP_Network class.

See #55646.

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

[SergeyBiryukov]

In 53411:

Docs: Add missing documentation for some Customize class properties:

• WP_Customize_Background_Image_Control::$type
• WP_Customize_Background_Image_Setting::$id
• WP_Customize_Header_Image_Setting::$id

Follow-up to [21037], [21053], [30885].

Props iamjaydip.
See #55646.

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

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

[SergeyBiryukov]

In 53436:

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

See #55646.

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

[whaze]

hello, it's my first contribution to WordPress, during the contribution's day at WCEU 2022

[audrasjb]

@whaze thanks for the PR! i added a few changes to your proposal, now we're good to ship it into core :)

[audrasjb]

In 53456:

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

Props whaze.
See #55646.

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

[audrasjb]

Replace "updated" with "deleted" in wpdb::delete

[audrasjb]

The above change was proposed on DevHub user contributed notes, by @cadlec.

[audrasjb]

In 53462:

Docs: Replace "updated" with "deleted" in wpdb::delete @return description.

Props audrasjb, cadlec.
See #55646.

[audrasjb]

In 53472:

Docs: Various fixes in wp-includes/pluggable.php docblocks, as per documentation standards.

See #55646.

[audrasjb]

In 53474:

Docs: Use third-person singular verbs for function descriptions in the Core Translation API.

See #55646.

[SergeyBiryukov]

In 53484:

Docs: Use typed array notation in some post function DocBlocks:

• wp_queue_posts_for_term_meta_lazyload()
• _prime_post_caches()

See #55646.

[SergeyBiryukov]

In 53502:

Docs: Add a missing word in pre_months_dropdown_query filter description.

Follow-up to [50163].

See #55646.

[SergeyBiryukov]

In 53503:

Docs: Add a comment for stripping the leading AND from SQL clauses in some query classes.

Follow-up to [30084], [34529], [34542], [36598], [37477], [37572], [43010].

See #55646.

[SergeyBiryukov]

In 53513:

Docs: Add @since notes for html5 theme feature changes in add_theme_support():

• As of WordPress 3.6.1, the html5 feature requires an array of types to be passed. Defaults to comment-list, comment-form, search-form for backward compatibility.
• As of WordPress 6.0, the previously added _doing_it_wrong() notice is actually displayed as expected.

Follow-up to [25193], [25235], [25785], [49344], [49354], [52828].

Props bobbingwide.
See #51657, #55646.

[audrasjb]

In 53514:

Docs: Use third-person singular verbs for function descriptions in the WP_Screen API.

See #55646.

[audrasjb]

In 53516:

Docs: Use third-person singular verbs for function descriptions in the Taxonomy Administration API.

See #55646.

[audrasjb]

In 53539:

Docs: Use third-person singular verbs for function descriptions in the Feed API, as per docblock standards.

See #55646.

[johnbillion]

In 53543:

I18N: Correct and improve inline docs and tests for functionality related to nooped plurals.

See #55646, #55652

[SergeyBiryukov]

In 53546:

Docs: Correct the return type for wp_save_image_file().

Since WordPress 3.5, wp_save_image_file() uses WP_Image_Editor classes under the hood to save the images.

While the save() method in those instances returns array|WP_Error and is documented as such, the return type of the wp_save_image_file() function was still left as bool.

A better solution would be to adjust the function to return the documented boolean type. However, doing that after 20+ major WP releases would be a backward compatibility break, so the documentation is now updated instead.

Includes:

• Documenting the returned array using hash notation.
• Adding a @since note for the $image parameter expecting a WP_Image_Editor instance.
• Adding a @since note for the $filesize value being included in the returned array.

Follow-up to [22094], [22619], [52837].

Props jrf, SergeyBiryukov.
See #55646.

[SergeyBiryukov]

In 53547:

Docs: Improve documentation for WP_Image_Editor::save() and related functions.

Includes:

• Documenting the returned array using hash notation.
• Adding a @since note for the $filesize value being included in the returned array.

This affects:

• wp_generate_attachment_metadata()
• wp_get_attachment_metadata()
• WP_Image_Editor::save()
• WP_Image_Editor_GD::save() and ::_save()
• WP_Image_Editor_Imagick::save() and ::_save()

Follow-up to [22094], [22619], [52837], [53546].

See #55646.

[audrasjb]

In 53550:

Docs: Use third-person singular verbs for function descriptions in Tests_Sitemaps_wpSitemapsPosts, as per docblock standards.

See #55646.

[audrasjb]

In 53566:

Docs: Use third-person singular verbs for function descriptions in Bookmark related files, as per docblock standards.

This changeset updates bookmark.php and bookmark-template.php files.

See #55646.

[SergeyBiryukov]

In 53584:

Docs: Adjust some DocBlocks in wpdb per the documentation standards.

Includes:

• Wrapping long single-line comments to multi-line for better readability.
• Formatting code blocks to display correctly on the Code Reference.
• Other minor edits for consistency.

This applies to:

• wpdb::$allow_unsafe_unquoted_parameters
• wpdb::escape_identifier()
• wpdb::_escape_identifier_value()
• wpdb::prepare()
• wpdb::has_cap()

Follow-up to [53575].

See #52506, #55646.

[audrasjb]

In 53585:

Docs: Misc fixes in Shortcode API function and hook descriptions, as per documentation standards.

See #55646.

[SergeyBiryukov]

In 53635:

Docs: Add @since tags for wp_die() handlers in the PHPUnit test suite.

Follow-up to [289/tests], [28797], [41966], [53634].

See #55652, #55646.

[SergeyBiryukov]

In 53638:

Docs: Add @since tags for _doing_it_wrong() and deprecation notice handlers in the PHPUnit test suite.

This affects methods in the WP_UnitTestCase_Base class:

• ::expectDeprecated()
• ::expectedDeprecated()
• ::setExpectedException()
• ::deprecated_function_run()
• ::doing_it_wrong_run()

Follow-up to [25402], [25408], [25785], [37861], [40536], [40539], [40872], [51872], [53637].

See #55652, #55646.

[audrasjb]

In 53639:

Docs: Add missing docblock description for install_themes_upload().

See #55646.

[audrasjb]

In 53641:

Docs: Use third-person singular verbs for function descriptions in WP_Comments_List_Table class, as per docblock standards.

See #55646.

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

Pinging @SergeyBiryukov for another pair of eyes before commit :) Thanks!

[audrasjb]

In 53672:

Docs: Typo correction in WP_Application_Passwords docblocks.

Props im_niloy.
Fixes #56155.
See #55646.

[audrasjb]

In 53679:

Docs: Misc. docblock enhancements in WP_REST_Menu_Items_Controller class, as per docblock standards.

See #55646.

[audrasjb]

In 53689:

Docs: Add missing function descriptions in wp-admin/includes/update.php.

See #55646.

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

[SergeyBiryukov]

In 53690:

Docs: Improve description for wp_plugin_update_rows() and wp_theme_update_rows().

Follow-up to [53689].

See #55646.

[SergeyBiryukov]

In 53703:

Docs: Document that allowed_tags() is no longer used in core as of WordPress 4.4.

Previously, it was used in core and older bundled themes to display the list of allowed tags in the comment form.

Follow-up to [709], [2009], [2012], [2032], [2040], [13030], [14365], [32858], [34316], [34351].

See #55646.

[audrasjb]

In 53727:

Docs: Fix indentation issues in block-template-utils.php docblocks, as per docs standards.

See #55646.

[audrasjb]

In 53728:

Docs: Use third-person singular verbs for function descriptions in block-template.php and block-template-utils.php.

See #55646.

[audrasjb]

In 53740:

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

See #55646.

[audrasjb]

In 53742:

Docs: Add missing function description in wp-admin/includes/comment.php.

See #55646.

[audrasjb]

In 53743:

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

See #55646.

[audrasjb]

In 53746:

Docs: Add missing function description in wp-admin/includes/template.php.

This changeset also includes a few docblock standards fixes in the same file.

See #55646.

[audrasjb]

In 53757:

Docs: Provide a more accurate description for wp_is_theme_directory_ignored().

This function doesn't filter theme directories, it rather determines whether a directory should be ignored during export.

Props audrasjb, nareshbheda.
Fixes #56257.
See #55646.

[audrasjb]

In 53765:

Docs: Fix indentation issues in wp_read_video_metadata and wp_read_audio_metadata docblocks.

Follow-up to [53764].

See #55646.

[audrasjb]

In 53766:

Docs: Add function description and @since mention for get_upload_iframe_src().

Follow-up to [14015].

See #55646.

[SergeyBiryukov]

In 53768:

Docs: Document that the $file_format parameter of metadata filters can be null.

This affects the wp_read_video_metadata and wp_read_audio_metadata filters.

Follow-up to [41746], [53764].

See #55646, #55828.

[SergeyBiryukov]

In 53770:

Docs: List the expected type first in a few functions:

• is_allowed_http_origin()
• doing_filter()
• wp_get_post_revisions_url()

Follow-up to [28010], [28889], [30674], [46696], [47060], [48068], [49929], [49963], [52095], [51286], [52111].

See #55646.

[audrasjb]

In 53775:

Docs: Refine @return docblock mentions for esc_sql(), wp_slash() and wp_unslash().

Props malthert, SergeyBiryukov, johnbillion, desrosj, byohann6.
Fixes #53946.
See #55646.

[audrasjb]

In 53776:

Docs: Remove an obsolete function description in addslashes_gpc().

• Usage of get_magic_quotes_gpc() was removed from addslashes_gpc() in [46105] / #47783.
• A similar description fragment was removed from wp_parse_str() in that changeset, but this one was missed.
• The get_magic_quotes_gpc() function itself was deprecated in PHP 7.4 and removed in PHP 8.0.

Props mitweka, audrasjb, SergeyBiryukov.
Fixes #56233.
See #55646.

[audrasjb]

In 53780:

Docs: Improve parameter descriptions in render_block and render_block_* filters.

The former $block_content parameter descriptions were too opinionated as block content can be appended, prepended, nested, removed, etc.

Props milana_cap.
Fixes #56286.
See #55646.

[audrasjb]

In 53792:

Docs: Various docblock improvements in Export Administration API, as per docs standards.

See #55646.

[audrasjb]

In 53794:

Docs: Various docblock improvements in Importer Administration API, as per docs standards.

See #55646.

[audrasjb]

In 53798:

Docs: Various docblock fixes in WP_Date_Query class, as per docs standards.

See #55646.

[audrasjb]

In 53799:

Docs: Fix $feature parameter type in block_has_support().

In block_has_support() docblock, the $feature parameter is an array, not a string.

Props Soean, audrasjb.
Fixes #56307.
See #55646.

[SergeyBiryukov]

In 53800:

Docs: Use more inclusive language in PHPCS configuration files.

Follow-up to [42346], [43348], [45455], [46290], [46820], [48121], [48477].

See #55646, #55647.

[SergeyBiryukov]

In 53809:

Docs: Improve description for doing_filter() and doing_action().

This corrects a note about did_action() return type, and brings more consistency between the two DocBlocks.

Follow-up to [27294], [53803].

See #55646.

[audrasjb]

In 53811:

Docs: Improve the description of param $list in wp_list_sort() docblock.

Props audrasjb, rherault.
Fixes #56324.
See #55646.

[audrasjb]

In 53814:

Docs: Use third-person singular verbs for function descriptions in WP_REST_Posts_Controller, as per docblocks standards.

See #55646.

[johnbillion]

In 53827:

Docs: Various corrections and improvements to inline documentation.

See #55646

[SergeyBiryukov]

In 53831:

Docs: Remove obsolete comment in object cache tests.

The comment mentioned creating two cache objects with a shared cache directory, which was no longer the case.

Follow-up to [5/tests] [170/tests].

See #55646, #55652.

[audrasjb]

In 53837:

Docs: Provide a more accurate @return type for get_pages() function.

Props malthert, audrasjb, johnbillion, jigar-bhanushali.
Fixes #56330.
See #55646.

[audrasjb]

In 53843:

Docs: Various docblock fixes in wp-admin/includes/image.php class, as per docs standards.

See #55646.

[audrasjb]

In 53859:

Docs: Various docblock fixes in wp-includes/blocks.php, as per docs standards.

See #55646.

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

Honestly I wasn't aware of numbered variable names before, but TIL: it's already used several times in Core, like parse_db_host() for example.

Looks good to me at a glance but I think that if we're going to generalize this to many functions, we should probably open a Meta ticket to improve the docblock parser, as it looks pretty bugged on DevHub. For example, see ​https://developer.wordpress.org/reference/classes/wpdb/parse_db_host/

Yeah there's at least a bug with $0: ​https://developer.wordpress.org/reference/functions/wp_maybe_grant_site_health_caps/

Definitely something we should fix :)

Well spotted Jb, will you open a meta ticket?

Sure!

Meta ticket, for reference: ​https://meta.trac.wordpress.org/ticket/6433

[audrasjb]

In 53871:

Docs: Various docblock fixes in Core Taxonomy API, as per docs standards.

See #55646.

[audrasjb]

In 53873:

Docs: Clarify that register_taxonomy() only accepts lowercase values for the $taxonomy parameter.

This brings consistency with docblock used in register_post_type().

Props audrasjb, bengreeley, dipakparmar443.
Fixes #56352
See #55646.

Adds documentation for the arguments for registering a block style.

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

[johnbillion]

In 53876:

Docs: Remove code tags from WordPress function names within inline documentation.

Removing these code tags means the function name will be automatically linked on the developer.wordpress.org reference, which is more useful than just seeing the function name.

See #55646

[johnbillion]

In 53877:

Docs: Correct and improve the documented types for various functions and hooks.

See #55646

[johnbillion]

In 53878:

Docs: Miscellaneous inline documentation improvements.

See #55646

[johnbillion]

In 53879:

Docs: Revert two changes that need to instead be made upstream in the Gutenberg repo.

Partially reverts [53877].

See #55646

[johnbillion]

In 53881:

XML-RPC: Correct the documented arguments for XML-RPC server methods.

See #55646

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

[audrasjb]

In 53887:

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

See #55646.

[johnbillion]

In 53892:

Editor: Document the arguments for registering a block style.

See #55646

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

[audrasjb]

In 53905:

Docs: Use third-person singular verbs for function descriptions in WP_Tax_Query class, as per docblocks standards.

See #55646.

[desrosj]

In 53910:

Docs: Remove incorrect default value for $path argument of admin_url().

Props joyously, costdev.
See #55646.

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

[kebbet]

Found two small typos, adjusted in #PR3121.

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

[kebbet]

Changes obejct to object in ​https://github.com/WordPress/wordpress-develop/pull/3122

[desrosj]

In 53939:

Docs: Correct typo in wp_maybe_clean_new_site_cache_on_update() parameter description.

Props kebbet.
See #55646.

Thanks! Fixed in https://core.trac.wordpress.org/changeset/53939.

[audrasjb]

In 54063:

Docs: Use third-person singular verbs for various function descriptions, as per docblocks standards.

This addresses various files modified in changeset [54062].

See #55646.

[kebbet]

What is the status for this PR, is anything blocking it?
​https://github.com/WordPress/wordpress-develop/pull/3121

@SergeyBiryukov Can you please check it as the changes make sense to merge?

LGTM 👍

[SergeyBiryukov]

In 54081:

Docs: Simplify a comment in WP_Network_Query::get_networks() and WP_Site_Query::get_sites().

This aims to improve readability. The arguments ignored are listed in the line directly below, so there is no need to mention them twice.

Follow-up to [41059], [41063], [53097], [53098], [54080].

See #55646.

[SergeyBiryukov]

In 54082:

Docs: Add a @since note for the update_network_meta_cache parameter of WP_Network_Query::__construct().

Follow-up to [54080].

See #55646.

[audrasjb]

In 54114:

Docs: Various docblock fixes in Site Health related files, as per documentation standards.

This addresses some files modified in changeset [54113].

See #55646.

[audrasjb]

In 54115:

Docs: Various docblock fixes in wp-includes/update.php, as per documentation standards.

This addresses some files modified in changeset [54113].

See #55646.

[audrasjb]

In 54116:

Docs: Clarify wp-includes/update.php main docblock description.

Props costdev, audrasjb.
See #55646.

[SergeyBiryukov]

In 54157:

Docs: Correct @return value for wp_get_http_headers().

Following the update to replace the HTTP API internals with Requests library in WordPress 4.6, the return value of wp_remote_retrieve_headers() has changed from a simple array to an object which implements ArrayAccess.

Since wp_get_http_headers() directly returns the result of wp_remote_retrieve_headers(), its return value should reflect that change.

Includes:

• Updating the return value for the deprecated wp_get_http() function, which also directly returns the result of wp_remote_retrieve_headers().
• Minor DocBlock formatting changes for some other HTTP API functions per the documentation standards.

Follow-up to [2416], [6390], [8092], [9013], [37428], [37989], [38730].

Props mhkuu.
See #54225, #55646.

[audrasjb]

In 54172:

Docs: Add missing @since history in Gallery Shortcode function.

Props bengreeley, audrasjb, desrosj, mukesh27.
Fixes #56206.
See #55646.

[audrasjb]

In 54173:

Docs: Use third-person singular verbs in Media API function descriptions, as per docblocks standards.

See #55646.

[SergeyBiryukov]

In 54178:

Docs: Clarify documentation for the nav_menu_item_id filter.

This aims to make it clear that the filter is applied to an HTML ID attribute for the menu item's <li> element, and not a numeric ID.

Follow-up to [15407], [25410], [27201], [38559], [51739].

Props dilipbheda, robinwpdeveloper, mukesh27, audrasjb, SergeyBiryukov.
See #56574, #55646.

[audrasjb]

In 54179:

Docs: Clarify that get_page_template() doesn't work on block themes.

When working on a block theme, locate_block_template() should be used instead of get_page_template(). This changeset updates the docblock of this function accordingly.

Props audrasjb, costdev, robinwpdeveloper.
Fixes #56394.
See #55646.

[audrasjb]

In 54180:

Docs: Use third-person singular verbs in Template Loading functions descriptions, as per docblocks standards.

See #55646.

[audrasjb]

In 54199:

Docs: Typo correction in _load_textdomain_just_in_time() docblock.

Props kebbet.
See #55646.

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

[SergeyBiryukov]

In 54224:

Docs: Correct the wording in wp_lostpassword_url() description.

This affects:

• The wp_lostpassword_url() function.
• The lost_password_html_link filter.

The filter description was copied from the function, which appears to be not quite accurate, as the lost password can only be reset, not retrieved.

Follow-up to [11448], [54206].

See #55646.

[johnbillion]

In 54267:

Docs: Various improvements and corrections to inline docs.

See #55646

[hellofromTonya]

In 54275:

Docs: Fix wp_get_layout_style() parameter documentation.

• Changed boolean to bool.
• Added Optional. and Default for each optional parameter.
• Improved @return documentation to include empty string.

Follow-up to [54274], [53421], [53085], [52069].

Props mukesh27, hellofromTonya.
See #55646.

[johnbillion]

In 54284:

Docs: Updates and corrections to various inline docs added in 6.1.

See #55646

[johnbillion]

In 54285:

Docs: Remove a change that needs to instead be applied in the Gutenberg repo.

See ​https://github.com/WordPress/gutenberg/pull/44342

See #55646

[audrasjb]

In 54286:

Docs: Fix prev_text and next_text parameters type in paginate_links().

Props gabri3lmarques, maximemeganck.
Fixes #56622.
See #55646.

[SergeyBiryukov]

In 54287:

Docs: Use typed array notation for the $locales parameter in plugin update filters.

The value comes from get_available_languages(), which returns an array of strings.

This affects:

• plugins_update_check_locales filter.
• update_plugins_{$hostname} filter.

Follow-up to [36630], [46660], [50921], [53933], [54284].

See #55646.

[johnbillion]

In 54318:

Docs: Increase the specificity of various property documentation.

See #55646

[audrasjb]

In 54347:

Docs: Various docblock fixes in wp-includes/revision.php, as per documentation standards.

See #55646.

Use C instead of С in docblock for get_test_theme_version.

https://core.trac.wordpress.org/ticket/55646

[kebbet]

In ​#PR3365 the cyrillic letter С is removed and the latin letter C is added. See ​https://en.wikipedia.org/wiki/Es_(Cyrillic)

[davidbaumwald]

In 54353:

Docs: Use Latin C instead of Cyrillic С in docblock for get_test_theme_version().

Follow-up to [48168].

Props kebbet.
See #55646.

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

[davidbaumwald]

In 54359:

Docs: Add @since to wp_enqueue_classic_theme_styles() docblock.

Follow-up to [54358].

Props kebbet.
See #55646.

[davidbaumwald]

In 54360:

Editor: Ensure settings for fluid typography and spacingScale are not lost on theme export.

This change adds fluid typography as a valid setting and removes spacingScale from the array of presets.

Props glendaviesnz, ramonopoly, tellthemachines.
See #55646.

[audrasjb]

In 54391:

Docs: Various docblock fixes in WP_Rewrite class, as per documentation standards.

See #55646.

[audrasjb]

In 54411:

Docs: Various docblock fixes in WP_Theme_JSON class, as per documentation standards.

Follow-up to [54408].

See #55646.

[audrasjb]

In 54412:

Docs: Various docblock fixes in global-styles-and-settings.php, as per documentation standards.

Follow-up to [54408].

See #55646.

[audrasjb]

In 54441:

Docs: Improve wp_get_object_terms() return type.

Props dd32, audrasjb, desrosj, mukesh27.
Fixes #56327.
See #55646.

[johnbillion]

In 54470:

Docs: Various improvements to inline docblocks.

See #55646

[desrosj]

#56792 was opened for 6.2. With RC1 today, going to close this out. Additional updates can be added here during RC if needed.

[SergeyBiryukov]

In 54504:

Docs: Fix typo in a @since note for _get_cron_array().

Follow-up to [53791].

Props kebbet.
See #55646, #56792.

[audrasjb]

In 54505:

Docs: Inline comment typo correction in wp_image_file_matches_image_meta().

Props kebbet.
See #55646, #56792.

[audrasjb]

In 54506:

Docs: Fix $cache_headers param type in site_status_page_cache_supported_cache_headers.

Follow-up to [54043].

Props skithund.
Fixes #56805.
See #55646.