Docblock improvements for 6.2

[desrosj]

Previously:

• #55646 (6.1)
• #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)

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

[kebbet]

There is no consensus on how to use behaviour and behavior in Core atm. Is this something that should be adressed/fixed?

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

[SergeyBiryukov]

In 54504:

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

Follow-up to [53791].

Props kebbet.
See #55646, #56792.

[audrasjb]

@kebbet we have a lot more "Behavior" occurrences than "Behaviour", so I'd say the current main consensus is "Behavior".

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

[SergeyBiryukov]

Replying to kebbet:

There is no consensus on how to use behaviour and behavior in Core atm. Is this something that should be adressed/fixed?

Per the ​spelling guidelines, American English should be preferred, so I think we should standardize on behavior.

[kebbet]

Thanks for making it clear @SergeyBiryukov!

I've added a PR with suggestions in PHP-files. I left out what i thought was included packages from others.
I've not touched CSS or JS files yet.

[audrasjb]

In 54505:

Docs: Inline comment typo correction in wp_image_file_matches_image_meta().

Props kebbet.
See #55646, #56792.

[desrosj]

@kebbet could you open a new ticket for this?

I've taken a brief look, and seems there are a few other occurrences of -ise vs. -ize and -or vs. -our that we should correct all at once.

For example, I see a couple of colour where it should be color, one occurrence of organise (American English is organize). Would be good to take a full pass for any. I used ​this page as a reference.

This could loosely be categorized as coding standards, but I think it deserves it's own ticket to for discussion and easier reference later on.

committed in https://core.trac.wordpress.org/changeset/54505

[kebbet]

Replying to desrosj:

@kebbet could you open a new ticket for this?

Of course, #56811 was just created!

[audrasjb]

In 54655:

Docs: Add missing default parameter value in themes_api() docblock.

Props rezakhan995, costdev.
Fixes #56862.
See #56792.

[audrasjb]

In 54656:

Docs: Add missing default parameter value in trackback_response() docblock.

Props rakibwordpress, audrasjb, SergeyBiryukov.
Fixes #56867.
See #56792.

[jorbin]

In 54657:

Revert accidental 5.9 branch commits [54655] and [54656]

Unprops audrasjb.
See #56867, #56792, #56862, #56792.

[jorbin]

In 54658:

Docs: Add missing default parameter value in trackback_response() docblock.

Previously: [54656] [54657]

Props rakibwordpress, audrasjb, SergeyBiryukov.
Fixes #56867.
See #56792.

[jorbin]

In 54659:

Docs: Add missing default parameter value in themes_api() docblock.

Previously: [54655] [54657]

Props rezakhan995, costdev.
Fixes #56862.
See #56792.

[audrasjb]

In 54663:

Docs: Align spelling with American English.

This changeset replaces "behaviour" with "behavior" in various docblocks.

Props kebbet, jrf.
See #56811, #56792.

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

[audrasjb]

In 54664:

Docs: Align spelling with American English.

This changeset replaces "cancelled" with "canceled" in various docblocks, per the ​Spelling Guidelines.

Props costdev.
See #56811, #56792.

[SergeyBiryukov]

In 54727:

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.

Previously committed in [53205], this appears to be accidentally reverted in [53562].

Follow-up to [53204], [53205], [53562].

Props audrasjb.
See #56792.

[audrasjb]

Reported on DevHub by @aleksganev, about wp_dropdown_users().

In the “Parameters” section, in the description of “option_none_value”, the variable “$show_option_non” is misspelled and should be “$show_option_none”

The description in question:
“Value to use for $show_option_non when no users were found. Default -1.”

I'm going to commit a fix directly.

[audrasjb]

In 54738:

Docs: Typo correction in wp_dropdown_users() docblock.

Props aleksganev.
See #56792.

[SergeyBiryukov]

In 54741:

Docs: Update comments in wp_nav_menu() tests per the documentation standards.

Includes:

• Fixing a few typos.
• Using the correct format for multi-line comments.
• Removing some comments that duplicate the assertion messages without providing any additional context.

Follow-up to [54478].

See #56792.

[SergeyBiryukov]

In 54747:

Docs: Add brackets to a function name in get_page_template() description.

This ensures the locate_block_template() function name is correctly linked in the Developer Reference.

Follow-up to [54179].

See #56792.

[SergeyBiryukov]

In 54755:

Docs: Correct DocBlock formatting for wp_sitemaps_enabled filter.

Follow-up to [48072], [48094], [48523].

See #56792.

[audrasjb]

In 54759:

Docs: Replace HTTP links with HTTPS in class-json.php docblocks.

Props haritpanchal.
Fixes #57017.
See #56792.

[audrasjb]

In 54775:

Docs: Replace HTTP links with HTTPS in class-pop3.php docblocks and JS vendor readme file.

Props rajeshraval786, hiren1094.
See #57017, #56792.

[audrasjb]

In 54776:

Docs: Fix block_editor_rest_api_preload() parameter type.

This changeset fixes the $preload_paths parameter type for block_editor_rest_api_preload() and related hooks. This parameter expects an array of strings OR an array where the path is the first element (index 0) of this array.

Props chouby.
Fixes #56810.
See #56792.

The changes below are a follow on from previous work to improve docblocks information in code.

The PR contains a small number of changes from a list of missing values - each file has a single commit to allow for cherry-picking.

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

[audrasjb]

In 54794:

Docs: Improve globals documentation in unregister_taxonomy() and wp_term_is_shared().

Props upadalavipul, mukesh27.
Fixes #57058.
See #56792.

Thanks for the review and feedback @costdev - i've committed the fixes and also picked up some more inconsistencies in my searching 😄

[desrosj]

In 54808:

Docs: Update comments in wp_nav_menu() tests per the documentation standards.

Includes:

• Fixing a few typos.
• Using the correct format for multi-line comments.
• Removing some comments that duplicate the assertion messages without providing any additional context.

Follow-up to [54478].

Props SergeyBiryukov.
Merges [54741] to the 6.1 branch.
See #56792, #56946.

[audrasjb]

In 54833:

Docs: Various docblock fixes in Multisite administration functions.

See #56792.

[audrasjb]

In 54835:

Docs: Typo correction in get_registered_nav_menus() docblock.

Props nithins53.
Fixes #57101.
See #56792.

[SergeyBiryukov]

In 54842:

Docs: Minor DocBlock edits for get_adjacent_post() and related functions.

This aims to better match the line wrapping recommendations of the documentation standards.

Follow-up to [16951], [28111], [32606], [37254].

See #56792.

Fix a typo in the PRESETS_METADATA constant description, in WP_Theme_JSON

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

[SergeyBiryukov]

In 54853:

Docs: Fix typo in the WP_Theme_JSON::PRESETS_METADATA constant description.

Follow-up to [53129].

Props kebbet, mukesh27.
See #56792.

Thanks for the PR! Merged in r54853.

[SergeyBiryukov]

In 54854:

Docs: Update wp_count_posts and wp_count_attachments filter descriptions.

This aims to match the wording generally used for other filters as per the documentation standards.

Follow-up to [25554], [25578], [25579], [53456].

See #56792.

[SergeyBiryukov]

In 54855:

Docs: Update various DocBlocks and inline comments per the documentation standards.

Includes minor formatting edits for consistency.

Follow-up to [53/tests], [12179], [12946], [35288], [37884], [38810], [38928], [46596], [48131], [52955], [53548], [53813], [53873], [54118], [54316], [54420], [54421], [54803].

See #56792.

[SergeyBiryukov]

In 54859:

Docs: Fix typo and improve DocBlock formatting in wp-admin/install-helper.php.

Follow-up to [236], [265], [8645], [30542].

See #56792.

[audrasjb]

In 54867:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul, mukesh27, krupalpanchal, jigar-bhanushali.
See #57069, #56792.

[audrasjb]

In 54868:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul.
See #57069, #56792.

[audrasjb]

In 54873:

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

See #56792.

[audrasjb]

In 54874:

Docs: Various docblock fixes in Block Supports related functions.

See #56792.

[audrasjb]

In 54876:

Coding Standards: Fix brace indentation in wp-align/includes/noop.php.

Props alberuni-azad.
Fixes #57209.
See #56792.

[audrasjb]

In 54877:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul.
See #57069, #56792.

[audrasjb]

In 54883:

Docs: Add missing parameter descriptions in wp-admin/includes/template.php.

Props mahekkalola, costdev, audrasjb, riccardodicurti.
Fixes #57208.
See #56792.

[audrasjb]

In 54953:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul.
See #57069, #56792.

[SergeyBiryukov]

In 54954:

Docs: Add missing type for $_wp_theme_features in WP_Debug_Data::debug_data().

Includes moving the global declaration to the top of the method for consistency.

Follow-up to [44986], [54953].

See #57069, #56792.

[SergeyBiryukov]

In 54957:

Docs: Improve DocBlock formatting for get_post_class().

Follow-up to [9273], [27429], [31271], [37544].

See #56792.

[SergeyBiryukov]

In 54958:

Docs: Mark some optional parameters as such in wp-includes/comment-template.php.

This affects:

• get_comment_class()
• comment_class()
• get_comment_excerpt()
• comment_excerpt()
• get_comment_link()
• get_comment_text()
• comment_text()
• comments_open()
• pings_open()
• get_comment_reply_link()
• comment_reply_link()
• post_reply_link()
• comment_form()

Follow-up to [25567], [27156], [33961].

See #56792.

[audrasjb]

In 55002:

Docs: Update docs for image_sideload_extensions filter to include webp in the list of allowed extensions.

Follow-up to [50810].

Props dimadin.
Fixes #57346.
See #56792.

[audrasjb]

In 55003:

Docs: Improve various globals documentation, as per docblock standards.

Props upadalavipul, audrasjb.

See #57069, #56792.

[SergeyBiryukov]

In 55004:

Twenty Seventeen: Document the $twentyseventeencounter global.

Follow-up to [38833], [38986], [55003].

See #57069, #56792.

[SergeyBiryukov]

In 55029:

Tests: Bring some consistency to mocking HTTP requests in unit tests.

Includes:

• Renaming the $preempt parameter to $response in the pre_http_request filter to better match the context used in callbacks (returning the original value if the conditions are not met rather than preempting the request).
• Synchronizing parameter names and types in various pre_http_request callbacks in unit tests.

Follow-up to [34509], [37907], [40628], [40629], [45667], [46175], [48242], [48462], [49904], [51021], [51973], [52146], [52382], [54043], [54968].

See #56793, #56792.

[audrasjb]

In 55043:

Docs: Align spelling with American English.

This changeset updates the use of "-ise" suffix to American English "-ize" in docblocks.

Follow-up to [54663], [54664].

Props ironprogrammer, costdev.
See #56811, #56792.

[audrasjb]

In 55044:

Docs: Align spelling with American English.

This changeset updates the use of "-ise" suffix to American English "-ize" and replaces "behaviour" with "behavior" in various docblocks.

Follow-up to [54663], [54664], [55043].

Props kebbet.
See #56811, #56792.

[audrasjb]

In 55051:

Docs: Align spelling with American English.

This changeset updates the use of "-ise" suffix to American English "-ize" in various files.

Follow-up to [54663], [54664], [55043], [55044].

Props kebbet, mukesh27.
See #56811, #56792.

[audrasjb]

In 55071:

Docs: Improve wp_style_add_data() function description.

This changeset removes an extra apostrophe in wp_style_add_data() DocBlock.

Props lanacodes, ashrafulsarkar, SergeyBiryukov.
Fixes #57466.
See #56792.

[audrasjb]

In 55072:

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

See #56792.

[audrasjb]

In 55073:

Docs: Typo correction in POP3 class send_cmd() inline docs.

Props nitman43, manojkpatil, kebbet.
Fixes #57449.
See #56792.

[audrasjb]

In 55074:

Docs: Add a missing quote to wp_is_large_network() Docblock params.

Props lanacodes.
Fixes #57468.
See #56792.

[audrasjb]

In 55075:

Docs: Various docblock fixes in Multisite WordPress API related functions.

Follow-up to [55074].

See #56792.

[audrasjb]

In 55080:

Docs: Remove unused post_modified and post_modified_gmt params from wp_insert_post() docblock.

Props dshanske, mehulkaklotar.
Fixes #57473.
See #56792.

I just noticed that we forgot this PR.
@pkevan could you please resolve the two small conflicts, so we can commit this PR?
Thanks!

no problem @audrasjb - the conflicts should be resolved.

[audrasjb]

In 55123:

Docs: Various improvements in ms-blogs.php function descriptions, as per docblocks standards.

See #56792.

[SergeyBiryukov]

In 55128:

Docs: Add missing @since tag for WP_Theme_JSON_Resolver::remove_json_comments().

Follow-up to [54162].

See #56792.

[hellofromTonya]

In 55144:

Docs: Update $types param for wp_get_global_stylesheet().

In 6.1.0, the values the $types parameter accepts changed to include 'base-layout-styles'.

This commit updates the DocBlock to reflect this change and provide clear information of what the function will load if no types are passed to it.

Reference:

• ​https://github.com/WordPress/gutenberg/pull/46817

Follow-up to [54162], [52054].

Props oandregal, jorgefilipecosta , ntsekouras.
Fixes #57563.
See #56792.

[johnbillion]

In 55170:

Cron API: Improve the docs for some cron event and cron schedule related functions.

See #56792

[SergeyBiryukov]

In 55173:

Docs: Improve documentation for block pattern properties.

Includes:

• Adding the templateTypes property to the WP_Block_Patterns_Registry::register() DocBlock.
• Adding @since notes for the postTypes and templateTypes properties to:
  • _register_theme_block_patterns()
  • WP_Block_Patterns_Registry::register()
• Bringing some consistency to the order of properties between:
  • _register_theme_block_patterns()
  • WP_Block_Patterns_Registry::register()
  • WP_REST_Block_Patterns_Controller::prepare_item_for_response()
  • WP_REST_Block_Patterns_Controller::get_item_schema()

Follow-up to [52943], [53152], [54263], [55168].

See #56792.

[SergeyBiryukov]

In 55174:

Docs: Document the inserter property in WP_Block_Patterns_Registry::register().

Follow-up to [53152], [55173].

See #56792.

[SergeyBiryukov]

In 55202:

Docs: Improve the DocBlock for get_attached_file().

Includes:

• Using 3-digit format for the @since tag.
• Minor wording updates and formatting corrections.

Follow-up to [3203], [4612], [6379], [8203], [24983], [29090], [55199].

See #51780, #56792.

[SergeyBiryukov]

In 55222:

Docs: Use consistent format for the @return tags in _wp_object_name_sort_cb() and _wp_object_count_sort_cb().

Both functions are used as a callback for uasort().

Follow-up to [36013], [55214].

See #57358, #56792.

[johnbillion]

In 55293:

Docs: Miscellaneous improvements and corrections to docblocks.

See #56792

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

[audrasjb]

In 55311:

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

See #56792.

Thanks @costdev I can't find any other files in my search.

Thanks @costdev I can't find any other files in my search.

[audrasjb]

In 55316:

Docs: Various improvements in XML-RPC Class function descriptions, as per docblocks standards.

See #56792.

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

[kebbet]

​PR 4079 sets the since version to 6.2.0 for all occurences of 6.1.2, beacause no 6.1.2 is released yet.

Thanks for spotting this!
One related commit: https://core.trac.wordpress.org/changeset/55010

Another commit -> https://core.trac.wordpress.org/changeset/55345

A third: https://core.trac.wordpress.org/changeset/54999

And https://core.trac.wordpress.org/changeset/54973
Origin ticket was reopened for 6.1.2 https://core.trac.wordpress.org/ticket/57169#comment:5

Thanks @kebbet for PR.

One move related commit: https://core.trac.wordpress.org/changeset/54894

Thanks @kebbet for PR.

One move related commit: https://core.trac.wordpress.org/changeset/54894

[audrasjb]

In 55349:

Docs: Use correct 6.2.0 @since version in multiple docblocks.

Props kebbet, audrasjb, mukesh27.
See #56792.

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

[audrasjb]

In 55355:

Docs: Replace HTTP with HTTPS in PHP Manual links located in wp-load.php.

Props shamimmiashuhagh.
See #56792.

[audrasjb]

In 55356:

Docs: Replace HTTP with HTTPS in PHP Manual links located in WP_Privacy_Policy_Content class.

Follow-up to [55355].

See #56792, #57017.

[SergeyBiryukov]

In 55363:

Docs: Add www. prefix to some PHP manual links in code comments.

This avoids an extra redirect and brings more consistency with other links to the PHP website in core.

Follow-up to [42980], [50914], [55355].

See #56792.

[SergeyBiryukov]

In 55393:

Tests: Remove duplicate DocBlock opening characters in tests/theme/wpTheme.php.

Follow-up to [814/tests], [904/tests], [50967].

Props mukesh27, costdev.
See #56792.

Thanks for the PR! Merged in r55393.

[SergeyBiryukov]

In 55398:

Docs: Document default values for optional parameters in various DocBlocks.

Props paulkevan, costdev, audrasjb, SergeyBiryukov.
See #56792.

Thanks for the PR! Merged in r55398 with some edits:

• Clarified the actual behavior where appropriate, e.g. "Defaults to the current post author" instead of just "Default false".
• Skipped a few instances of "Default empty array" when the array does in fact include some default values early in the function. Clarified those values where they were missing.

[hellofromTonya]

#57840 is now open for the ongoing Docblock improvements in the 6.3 cycle.

[audrasjb]

In 55472:

Bundled Themes: Improve various globals documentation, as per docblock standards.

Props viralsampat, audrasjb, costdev.
See #56792, #57069.

[audrasjb]

In 55485:

Docs: Add missing 6.2.0 @since mention in get_the_privacy_policy_link().

Follow-up to #55261.

See #56792, #56345.

[audrasjb]

In 55492:

Docs: Add security warning in remove_query_arg() docblock to make it consistent with add_query_arg().

Props roytanck.
Fixes #57885.
See #56792.

[costdev]

As we're about to enter RC, closing this ticket out for 6.2. If any changes are needed for backport to the 6.2 branch, feel free to reopen this ticket.