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.