Docblock improvements for 6.3

[hellofromTonya]

Previously:

• #56792 (6.2)
• #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)

[SergeyBiryukov]

In 55539:

Docs: Improve some DocBlock formatting in wp-includes/class-wp-xmlrpc-server.php.

Includes clarifying the list of fields passed to the xmlrpc_default_*_fields filters by default.

Follow-up to [16046], [17647], [27730], [32550], [37492], [55316].

See #57840.

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

[pouicpouic]

Hi, this is my first contribution, at WordCamp Paris April 2023.

[audrasjb]

Hi there, just noting that we are at WordCamp Paris contributor day right now, and we're going to use small Docblock changes to onboard people on the contribution process to Core :)

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

[laurentmagnin]

Hi, this is my first contribution, at WordCamp Paris April 2023.

[audrasjb]

In 55663:

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

Props pouicpouic.
See #57840.

[audrasjb]

In 55664:

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

Props pouicpouic.
See #57840.

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

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

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

[jbcouton]

Hi, this is my first core contribution, at WordCamp Paris April 2023.

[audrasjb]

In 55681:

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

Props laurentmagnin, pouicpouic, jbcouton, audrasjb.
See #57840.

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

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

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

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

[johnbillion]

In 55693:

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

See #57840

[johnbillion]

In 55694:

Docs: All sorts of improvements and corrections to function and hook docs.

See #57840

[audrasjb]

In 55705:

Docs: Various improvements in Bookmark Administration API function descriptions, as per docblocks standards.

Follow-up to [55704].

See #57840.

[johnbillion]

In 55711:

Docs: Corrections and improvements to docblocks for global styles, global settings, theme.json parsing, and shortcodes.

See #57840

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

There's many helpful code examples in the docs for the WP_HTML_Tag_Processor class but they're all indented by four unnecessary spaces. They use the <code>`php</code> wrapper which makes the indentation appear in the code blocks on the developer reference site. This fixes that by removing the extraneous indentation.

There's also an additional fix for the note about the U+FFFD character.

Example URLs that display the unnecessary indentation:

• ​https://developer.wordpress.org/reference/classes/WP_HTML_Tag_Processor/
• ​https://developer.wordpress.org/reference/classes/WP_HTML_Tag_Processor/is_tag_closer/

[johnbillion]

In 55712:

Docs: Miscellaneous formatting corrections to inline docs and whitespace.

See #57840

[johnbillion]

In 55714:

Filesystem API: Correct and improve the return type documentation for the dirlist() method in WP_Filesystem_Base and its extending classes.

Props mat-lipe, szepeviktor, costdev, audrasjb, johnbillion

Fixes #58229
See #57840

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

[johnbillion]

In 55718:

Docs: Improve formatting of markup in the docs for WP_HTML_Tag_Processor.

Code blocks wrapped inside backtacks don't need to be indented.

See #57840

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

[johnbillion]

In 55719:

Docs: Correct and improve inline docs relating to the style engine.

See #57840

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

Thanks @johnbillion - I was under the impression the indentation was required, but I've double-checked after this change and the code still renders as code at least in PHPStorm and VSCode.

@johnbillion what was wrong with the U+FFFD note?
looks right to me in the linked documentation, which I think is still reflecting the code before this change

I was under the impression the indentation was required

Yeah you just need either the backticks or the indentation but not both 😄

what was wrong with the U+FFFD note?

It was just to remove the unprintable character from the source code 👍

looks right to me in the linked documentation

Yeah the docs on the developer reference site only get regenerated from the source when each new version of WordPress is released

but not both

ahaa

It was just to remove the unprintable character from the source code 👍

that character _is_ printable though, and it printed

maybe it's confusing because _that character_ is the character used _when the string has invalid characters in it_?

I think maybe it was a mistake to remove. we added that originally to show what it is, thinking people would more readily recognize � than U+FFFD

Ohhhh _that_ is the actual unicode character displayed as a replacement when a character is unprintable? I see.

@johnbillion do you have any thoughts about me adding it back in? maybe surround it in quotes this time to try and make it more obvious that it's the actual character?

sorry this wasn't caught in review. I would have noted it, but the PR was created and merged before I was still asleep

[audrasjb]

In 55723:

HTML API: Restore mistakenly-removed content in documentation.

In [55718] the Unicode replacement character was mistakenly removed. The purpose of including the character was to communicate what it looks like and why the Tag Processor won't insert it into the document.

This changeset brings the character back and adds a small clue to fix the confusion that may lead to its removal.

Follow-up to [55718].

Props dmsnell.
Fixes #58256
See #57840.

[SergeyBiryukov]

In 55725:

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 [52049], [52051], [53331], [54156], [54214], [55203], [55719].

See #57840.

[johnbillion]

In 55732:

Docs: A host of corrections and improvements to inline documentation.

See #57840

[SergeyBiryukov]

In 55733:

Docs: Improve Style Engine file and class headers per the documentation standards.

Follow-up to [54156], [55719].

See #57840.

[SergeyBiryukov]

In 55734:

Docs: Improve HTML API file and class headers per the documentation standards.

Follow-up to [55203], [55304], [55718], [55724], [55727].

See #57840.

[johnbillion]

In 55753:

Docs: Various corrections and improvements to inline docs and docblocks.

See #57840

[SergeyBiryukov]

In 55819:

Docs: Improve Style Engine DocBlocks per the documentation standards.

Follow-up to [54156], [55719], [55733].

See #57840.

[SergeyBiryukov]

In 55820:

Docs: Correct default value for the $optimize option in Style Engine.

The default value is set to true in WP_Style_Engine_Processor::get_css(), but was previously documented as false in various DocBlocks.

Follow-up to [54156], [55719], [55733], [55819].

See #57840.

[dmsnell]

@SergeyBiryukov do you mind backporting the changes you made to the HTML API to Gutenberg? every update in Core needs to be followed by such a change so the two sides don't get out of sync. I'm happy to review/approve the "blessed" PR over there for you.

[SergeyBiryukov]

In 55824:

Docs: Fix a few more typos in inline comments.

Follow-up to [9117], [11005], [12097], [18632], [26192], [55823].

Props Presskopp.
See #58334, #57840.

[SergeyBiryukov]

Replying to dmsnell:

do you mind backporting the changes you made to the HTML API to Gutenberg? every update in Core needs to be followed by such a change so the two sides don't get out of sync.

I was not aware of that, thanks! Sure, will create a PR :)

[Presskopp]

More 'a' => 'an' candidates:

\src\wp-admin\includes\class-bulk-upgrader-skin.php

Line 82: Nothing, This will be displayed within a iframe.

\src\wp-admin\includes\class-pclzip.php

Line 637: read_error : the file was not extracted because there was a error

\src\wp-admin\includes\file.php

Line 1380: Check for a edge-case affecting PHP Maths abilities.

\src\wp-includes\class-wp-http-cookie.php

Line 139: Handle the cookie ending in ; which results in a empty final pair.

\src\wp-includes\class-wp-http.php

Line 1083: * '4' or '6' to represent a IPv4 and IPv6 address respectively.

\src\wp-includes\class-wp-oembed.php

Line 517: * Connects to a oEmbed provider and returns the result.

\src\wp-includes\media-template.php

Line 11: * Outputs the markup for a audio tag to be used in an Underscore template

\src\wp-includes\media.php

Line 4814: * Checks the HTML content for a audio, video, object, embed, or iframe tags.

\src\wp-includes\option.php

Line 1373: * Removes a option by name for the current network.

\src\wp-includes\Requests\src\IdnaEncoder.php

Line 29: * Maximum length of a IDNA URL in ASCII.

\src\wp-includes\customize\class-wp-customize-nav-menu-item-setting.php

Line 231: Note that a ID of less than one indicates a nav_menu not yet inserted.

[Presskopp]

went through them all again and this is the patch so far

[SergeyBiryukov]

In 55827:

Docs: Fix a few more typos in DocBlocks and inline comments.

Follow-up to [6779], [10565], [12023], [25224], [27533], [32806], [34777], [45262], [46594], [55823], [55824].

Props Presskopp.
See #57840.

[SergeyBiryukov]

In 55843:

Docs: Fix a few more typos in DocBlocks.

Follow-up to [39493], [41726], [55823], [55824], [55827].

See #57840.

[dmsnell]

Replying to SergeyBiryukov:

Replying to dmsnell:

do you mind backporting the changes you made to the HTML API to Gutenberg? every update in Core needs to be followed by such a change so the two sides don't get out of sync.

I was not aware of that, thanks! Sure, will create a PR :)

Thanks @SergeyBiryukov - you can use ​#48812 as an example.

This workflow is the result of developing the work in Core first and keeping Gutenberg in sync, since that seems to be how everyone prefers it, and since it's easier getting these updates into the plugin (we just need to make sure we do that).

Feel free to add me as a reviewer.

[audrasjb]

#58340 was marked as a duplicate.

[johnbillion]

In 55870:

Docs: Miscellaneous corrections and improvements to docblocks.

See #57840

[audrasjb]

In 55882:

Docs: Various docblock improvements in Custom Header Image related functions, as per docblocks standards.

See #57840.

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

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

[costdev]

@audrasjb ​PR 4551 and ​PR 4552 target some docblocks that are missing third-person singular verbs.

[audrasjb]

Thanks! 👀

[audrasjb]

In 55884:

Docs: Fix a few more typos in Docblocks.

Follow-up to [6779], [10565], [12023], [25224], [27533], [32806], [34777], [45262], [46594], [55823], [55824], [55827].

Props nazmulhudadev, mukesh27.
Fixes #58338.
See #57840.

[audrasjb]

In 55887:

Docs: Improve various docblock in WP_Query class, as per docblock standards.

See #57840.

[audrasjb]

In 55893:

Docs: Mark apply_filters() third parameter $args as optional.

The $args parameter of apply_filters() is optional. This changeset updates the related Docblock description accordingly so the parameter is not marked as
required on DevHub.

Props gaeldenysiak, audrasjb, gilles66.
Fixes #58481.
See #57840.

Added a commit to resolve a conflict.

[audrasjb]

In 55911:

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

Props costdev, audrasjb.
See #57840.

Thanks for the update!
Committed in https://core.trac.wordpress.org/changeset/55911

[audrasjb]

In 55916:

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

Follow-up to [55911].

Props costdev, audrasjb.
See #57840.

[audrasjb]

In 55917:

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

Follow-up to [55911], [55916].

Props costdev.
See #57840.

[audrasjb]

In 55918:

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

Follow-up to [55911], [55916], [55917].

Props costdev.
See #57840.

Thanks @costdev!
Committed in:

• https://core.trac.wordpress.org/changeset/55916
• https://core.trac.wordpress.org/changeset/55917
• https://core.trac.wordpress.org/changeset/55918

[audrasjb]

In 55952:

Docs: register_block_style() docblock improvement.

This changeset replaces style with style_handle in the description of $style_properties to better match WP_Block_Styles_Registry::register().

Follow-up to [46111], [48102].

Props bacoords, dilipbheda, audrasjb.
Fixes #58562.
See #57840.

[audrasjb]

In 55962:

Docs: Add missing param description to update_menu_item_cache in wp_get_nav_menu_items().

Because update_menu_item_cache parameter doesn't have any description in this function, the wp_get_nav_menu_items() documentation page on DevHub fallbacks
to get_post() params descriptions… which fallbacks to parse_query().

In parse_query(), the update_menu_item_cache param is set to false by default, so wp_get_nav_menu_items() ends up with a value of false by default,
which is wrong since wp_get_nav_menu_items() overrides this parameter to set it to true by default.

This changeset adds update_menu_item_cache parameter to wp_get_nav_menu_items() docblock, and indicates that it is set to true by default.

Follow-up to [53504].

Props audrasjb, matmoe.
Fixes #58468.
See #57840.

[sabernhardt]

Twenty Seventeen: correcting a typo and removing a word that never belongs in documentation (props mukesh27)

[audrasjb]

In 56118:

Twenty Twenty-One: Improve various globals documentation, as per docblock standards.

This changeset adds globals documentation, and also a couple Docblock standards improvements.

Props upadalavipul, audrasjb.
Fixes #58684.
See #57840.

[sabernhardt]

I added more to my patch and moved it to its own ticket: #58695.

[audrasjb]

In 56121:

Twenty Seventeen: Various docblock fixes.

Props sabernhardt, audrasjb.
Fixes #58695.
See #57840.

[audrasjb]

In 56122:

Docs: Fix image_get_intermediate_size() docblock.

The description of returned values in array was incorrect for image_get_intermediate_size():

• $file returns the filename of image, no path information
• $path returns path relative to the uploads directory, not absolute

Props crstauf, sccr410.
Fixes #58686.
See #57840.

[SergeyBiryukov]

In 56144:

Docs: Document the return value of wp_check_php_version() using hash notation.

Follow-up to [42832].

See #57840.

[audrasjb]

In 56153:

Docs: Use third-person singular verbs in various function descriptions of load.php, as per docblocks standards.

See #57840.

[johnbillion]

In 56157:

Docs: Correct the formatting of various filter documentation.

See #57840

[audrasjb]

In 56165:

Docs: Update link to MovableType documentation.

Props mujuonly.
Fixes #58760.
See #57840.

[costdev]

The $data parameter in WP_REST_Attachments_Controller::upload_from_data() is passed and treated only as string, not array.

[audrasjb]

In 56167:

Docs: Update link to MovableType docs (on Internet Archive).

Follow-up to [56165].

Props SergeyBiryukov.
Fixes #58760.
See #57840.

[audrasjb]

In 56168:

Docs: Docblock correction in WP_REST_Attachments_Controller::upload_from_data().

The $data parameter in WP_REST_Attachments_Controller::upload_from_data() is passed and treated only as string, not array.

Props costdev.
See #57840.

[audrasjb]

In 56204:

Docs: Fix incorrect type for $crop param is various WP_Image_Editor classes and methods.

This changeset updates the $crop docblock type in various WP_Image_Editor, WP_Image_Editor_GD and WP_Image_Editor_Imagick functions, to match the
type documented in image_resize_dimensions().

Props thunderdw.
Fixes #58271.
See #57840.

[SergeyBiryukov]

In 56231:

Docs: Clarify where the wp_get_development_mode() value is retrieved from.

Includes:

• Adding a mention of the WP_DEVELOPMENT_MODE constant.
• Minor DocBlock formatting adjustments.

Follow-up to [56042], [56223].

See #57487, #57840.

[SergeyBiryukov]

In 56232:

Docs: Use consistent wording for development mode.

Follow-up to [56042], [56223], [56231].

See #57487, #57840.

[audrasjb]

In 56256:

Docs: Fix various incorrect @since mentions.

Props costdev, mukesh27.
Fixes #58834.
See #57840.

[audrasjb]

In 56257:

Docs: Various docblocks corrections.

See #57840.

[audrasjb]

In 56272:

Docs: Fix indentation issue in WP_REST_Global_Styles_Revisions_Controller class.

Follow-up to [56082].

See #57840, #58524.

[audrasjb]

If any committer is available, I formally need a second committer sign-off to backport the above patch 👆

[joedolson]

Looks good!

[joedolson]

In 56280:

Docs: Fix indentation issue in WP_REST_Global_Styles_Revisions_Controller class.

Follow-up to [56082].
Reviewed by joedolson.
Merges [56272] to the 6.3 branch.
See #57840, #58524.

[audrasjb]

RC3 was just released. Let's close this one as fixed.
Thanks everyone!