Docblock improvements for WP 6.9

[desrosj]

Previously:

• #62281 (6.8)
• #61608 (6.7)
• #60699 (6.6)
• #59651 (6.5)
• #58833 (6.4)
• #57840 (6.3)
• #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)

[audrasjb]

In 60109:

Docs: Remove an unwanted trailing space found after [60108].

Follow-up to [60108].

See #63041, #63166.

[SergeyBiryukov]

In 60112:

Docs: Merge file-level and class-level DocBlocks in wp_get_canonical_url() test file.

Per the ​documentation standards, whenever possible, all WordPress files should contain a header DocBlock, regardless of the file’s contents – this includes files containing classes.

However, this recommendation makes less sense for unit test classes if not applied consistently, and the duplicate tags cause some confusion.

This commit aims to reduce confusion and avoid repeating information by combining the DocBlocks.

Includes using third-person singular verbs in test method descriptions, as per the documentation standards.

Follow-up to [55337], [60108], [60109].

See #63166.

[audrasjb]

In 60120:

Docs: Update inline docs for various general template functions.

Props dilipbheda, mukesh27.
Fixes #63215.
See #63166.

[SergeyBiryukov]

In 60121:

Docs: Correct the type of the $name parameter in get_template_part action.

The value cannot be null at this point, as it is converted to a string a few lines above.

Follow-up to [45059], [55870], [60120].

See #63215, #63166.

[jorbin]

In 60139:

Docs: Update inline docs for various general template functions.

Reviewed By peterwilsoncc, jorbin.
Merges [60120] and [60121] to the 6.8 branch.

Props dilipbheda, mukesh27, SergeyBiryukov, audrasjb.
Fixes #63215.
See #63166.

[johnbillion]

In 60178:

Docs: Improve and standardise the format of placeholder strings that get replaced within email messages.

This prevents the strings being treated as h3 headings by the documentation parser on developer.wordpress.org.

See #63166

[johnbillion]

In 60233:

Docs: Remove an unnecessary @return tag from this filter.

See #63166

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

See ​https://github.com/szepeviktor/phpstan-wordpress/issues/274

[johnbillion]

In 60236:

Docs: Declare the object shapes for some return values.

Props swissspidy

See #63166

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

The @internal tag is an odd one, it has a different meaning depending on whether it's used as a top-level tag or an inline tag. Quoting ​the phpDocumentor docs:

The @internal tag is used to denote that associated _Structural Elements_ are internal to the application or library. It may also be used inside a long description to insert a piece of text that is only applicable for the developers of the software.

So the former denotes that the symbol is for internal use only, and the latter denotes some internal documentation.

This PR fixes some instances of top level @internal tags that should be inline tags.

• Trac ticket: https://core.trac.wordpress.org/ticket/63166
• See ​https://github.com/php-stubs/wordpress-stubs/issues/287 CC @szepeviktor @jcvignoli.

[johnbillion]

In 60249:

Docs: Switch some @internal tags to the inline format so the corresponding function or method is not treated by IDEs and static scanning tools as internal use only.

See #63166

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

[johnbillion]

In 60254:

Docs: Correct the description of the wpdb::process_field_formats() return value.

See #63166

[johnbillion]

In 60264:

Docs: Improvements and corrections to documentation relating to metadata.

See #63166

[audrasjb]

In 60271:

Docs: Improve inline docs params for various category template tags functions.

Props dilipbheda, audrasjb, mukesh27.
Fixes #63225.
See #63166.

[SergeyBiryukov]

In 60272:

Docs: Mark WP_Debug_Data::get_sizes() as deprecated in WordPress 5.6.

Follow-up to [49154].

See #63166.

[SergeyBiryukov]

In 60276:

Docs: Correct alignment for some translator comments.

Follow-up to [49154].

See #63166.

[johnbillion]

In 60297:

Docs: Correct the documented types of the password algorithm constants in PHP 7.3 and earlier.

See #63166

While working on ​PR 9099, I discovered the valid_unicode function and was curious about the set of codepoints it allows.

"Valid unicode" does not seem self explanatory, however after discussion with @dmsnell and looking at the history,
it appears that this follows the XML definition of a valid unicode character. This is now references in the function
docblock. Additionally, the separate conditions are also documented to clarify how they correspond to each part of
the XML valid unicode character description.

The hexadecimal literals are capitalized to match the quoted specification.

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

MySQL isn't the only supported database server, so this updates docs and one i18n string to use more generic terminology.

• Trac ticket: https://core.trac.wordpress.org/ticket/63166
• Trac ticket: https://core.trac.wordpress.org/ticket/60037

[johnbillion]

In 60363:

Docs: Documentation and i18n string improvements relating to MySQL and server requirements.

See #63166

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

[jonsurrell]

In 60405:

Docs: Expand valid_unicode function documentation.

The valid_unicode() function accepts a limited set of codepoints according to the XML specification. Document the allowed codepoints and link to relevant documentation.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/9100.

Props jonsurrell, dmsnell.
See #6583, #63166.

Merged in [60405].

[johnbillion]

In 60416:

Docs: Add a few missing @since tags.

See #63166

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

Corrected @since Order in Inline Documents in Below Files:

• src/wp-admin/includes/class-wp-screen.php
• src/wp-admin/includes/misc.php
• src/wp-admin/includes/template.php

@SergeyBiryukov These one is ready for commit.

[johnbillion]

In 60437:

Docs: The recommended version of PHP is now 8.3 or greater.

Meta ticket: ​https://meta.trac.wordpress.org/ticket/6612

See #63166

[SergeyBiryukov]

In 60476:

Docs: Add a @since note for wp_get_attachment_image_attributes filter.

This adds a note that height and width attributes are passed to the filter as of WordPress 6.8.2.

Follow-up to [60415].

See #63166.

[audrasjb]

In 60525:

Docs: Docblock improvement in WP_REST_Font_Collections_Controller.

Props viralsampat , mukesh27.
Fixes #63744.
See #63166.

[audrasjb]

In 60526:

Docs: Typo correction and comment improvement in color-picker.css.

Props mujuonly, sabernhardt, dhruvang21.
Fixes #63196.
See #63166.

Rebased with Latest Trunk.

[johnbillion]

In 60652:

HTTP API: Various improvements to the docblocks for HTTP functions.

See #63166

[johnbillion]

In 60653:

Cron API: Correct the documented type and value of the $doing_wp_cron variable.

See #63166

[SergeyBiryukov]

In 60658:

Docs: Correct the order of @since and @global tags in some files.

Follow-up to [32642], [32643], [60416].

Props shailu25, mukesh27.
See #63166.

Merged in 60658

[SergeyBiryukov]

In 60682:

Docs: Correct the order of @since and @global tags in some files.

Follow-up to [9053], [13177], [16660], [32642], [37226], [54953], [59865], [60658].

Props viralsampat, shailu25, sandipsinh007.
Fixes #63879. See #63166.

Per the PHP ​manual, if a function omits return, the value null is returned.

wp_ext2type() either returns a string for known extensions or null when no match is found. The doc block is updated to reflect this: string|null.

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

This function returns the first matching file extension (e.g. 'jpg' for 'image/jpeg') or false if no match is found. The return description has been updated for clarity.

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

Thanks for the PR!

In core, I think we generally use null in the @return tag when the function has an explicit return null line. Otherwise, we use void, which is the case here. So it seems like this change would be inconsistent with the rest of core.

That said, we could perhaps reconsider this, but ideally in a consistent way 🙂

[SergeyBiryukov]

In 60696:

Docs: Clarify return value for wp_get_default_extension_for_mime_type().

Follow-up to [51653].

Props rollybueno, SergeyBiryukov.
See #63166.

Thanks for the PR! Merged in r60696.

Add descriptive text for @param and @return tags for standardization. No functional changes.

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

Thanks. Closing here then, we can think about that sometime in the future.

Add descriptive text for @param and @return tags for standardization.

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

[SergeyBiryukov]

In 60709:

Docs: Add @param and @return description for maybe_hash_hex_color().

Follow-up to [20936], [21354], [37283].

Props rollybueno, SergeyBiryukov.
See #63166.

Thanks for the PR! Merged in r60709.

[SergeyBiryukov]

In 60714:

Docs: Add @param and @return description for sanitize_hex_color_no_hash().

Follow-up to [20936], [21354], [37283], [60709].

Props rollybueno, SergeyBiryukov.
See #63166.

Thanks for the PR! Merged in r60714.

[SergeyBiryukov]

In 60724:

Docs: Correct the order of @see and @global tags in some files.

Follow-up to [28656], [29090].

Props shailu25, mukesh27.
See #63166.

Thanks for the PR! Merged in r60724.

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

[SergeyBiryukov]

In 60730:

Docs: Correct indentation for a multi-line comment.

Includes reformatting a long conditional for better readability.

Follow-up to [38086], [42343].

Props mukesh27, SergeyBiryukov.
See #63166.

Thanks for the PR! Merged in r60730.

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

Introduce in 56690 / #53232

[SergeyBiryukov]

In 60780:

Docs: Correct formatting for wp_img_tag_add_decoding_attr filter DocBlock.

Follow-up to [56690].

Props mukesh27.
See #63166.

Thanks for the PR! Merged in r60780.

Added @see tag before @param tag in Inline Documentation:

• src/wp-includes/class-wp-customize-widgets.php

Trac ticket: #63166

[SergeyBiryukov]

In 60802:

Docs: Correct the order of @see and @param tags in WP_Customize_Widgets.

Follow-up to [36586], [42630].

Props shailu25.
See #63166.

Thanks for the PR! Merged in r60802.

[SergeyBiryukov]

In 60889:

Docs: Correct formatting for some DocBlocks in Comment Template block tests.

Follow-up to [53172], [53298], [53336], [56262].

Props mukesh27.
See #63166.

[SergeyBiryukov]

In 60922:

Docs: Update MDN Web Docs link to avoid an extra redirect.

Follow-up to [41741], [59712].

See #63166.

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

[SergeyBiryukov]

In 60938:

Docs: Correct the tag order for site_status_good_response_time_threshold filter.

Follow-up to [54043].

Props mukesh27.
See #63166.

Thanks for the PR! Merged in r60938.

[SergeyBiryukov]

In 60978:

Docs: Correct DocBlock formatting for pre_site_option filter.

Includes bringing some consistency with the pre_option filter DocBlock.
.
Follow-up to [54145], [54948], [60959].

Props mukesh27, SergeyBiryukov.
See #37930, #63166.

[johnjamesjacoby]

Related: #63218

[johnjamesjacoby]

In 61087:

Docs: minor white-space correction.

This commit adds a missing space to the @return array of WP_REST_Post_Format_Search_Handler::prepare_item().

Props audrasjb, jigar-bhanushali, rollybueno.

See #63166.

Fixes #63218.

[SergeyBiryukov]

In 61141:

Docs: Synchronize WP_REST_Server::check_authentication() docs with the filter.

Follow-up to [34928], [55693].

See #63166.

[desrosj]

With RC1 in less than 24 hours and the branching of 6.9 immanent, I've created #64224 for the 7.0 release and will close this one out.

If there are further changes required for 6.9, this can be reopened or referenced in the commit message.