Docblock improvements for 6.5

[hellofromTonya]

Previously:

• #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)

Fixing minor style issues in the comments, after 6.3.2.

changed to https://core.trac.wordpress.org/ticket/59651

### Docs: fix incorrect @private tags

The @private tag doesn't exist and isn't supported. To indicate something is private when in the global namespace, @access private should be used instead.

### Docs: use proper case for @todo tags

The correct tag is @todo, not @TODO or @todo: (not the trailing colon).

### Docs: fix various incorrect WP-flavoured array specifications

Tags like @string or @array do not exist and are not supported. The way these were used here, also meant duplicate information being documented.

Fixed now by using the @type tag as per the WP flavour of array documentation.

Includes some fixes to the documentation formatting.

Ref: ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#1-1-parameters-that-are-arrays

### Docs: fix incorrect @return tag

@return[] is not a valid tag. Fixed now.

As this is a test, I've not bothered with the WP flavoured array annotation and just used the industry standard one.

### Docs: fix broken @covers tag

Without the space between the tag and the "description", the tag will not be recognized and the test will not record coverage correctly.

### Docs: fix incorrect property doc

The @array tag does not exist. This should be @var array.

### Docs: miscellaneous other doc fixes

• @contrib is not a valid tag.
• @origin is not a valid tag.
• @ref is not a valid tag.
• @blessed is not a valid tag and doesn't convey any meaningful information.
• @issue is not a valid tag.

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

[jrf]

I've just opened ​GitHub PR #5585 with 7 small doc tag related patches.

Issues discovered while testing a sniff I'm writing.

I'm aware that these patches touch some files related to Gutenberg, but it is unclear to me exactly which files are considered GB. I'll happily pull the changes to the GB project as well, once I know which belong there.

[SergeyBiryukov]

In 57062:

Docs: Fix typo in a function DocBlock in WP_Duotone tests.

Follow-up to [56101], [56981].

See #59651.

[SergeyBiryukov]

In 57065:

Docs: Replace incorrect @private tags.

The @private tag does not exist and is not supported. To indicate that something is private when in the global namespace, @access private should be used instead.

Reference: ​PHP Documentation Standards: PHPDoc tags.

Props jrf.
See #59651.

[SergeyBiryukov]

In 57077:

Docs: Use proper case for @todo tags.

The correct tag is @todo, not @TODO or @todo: (note the trailing colon).

Reference: ​PHP Documentation Standards: PHPDoc tags.

Follow-up to [55203], [56274], [56565], [56698].

Props jrf.
See #59651.

[SergeyBiryukov]

In 57099:

Docs: Fix various incorrect WP-flavored array specifications.

Tags like @string or @array do not exist and are not supported. The way these were used here, also meant duplicate information being documented.

Fixed now by using the @type tag as per the WP flavor of array documentation.

Includes some fixes to the documentation formatting.

Reference: ​PHP Documentation Standards: Parameters That Are Arrays.

Follow-up to [33322], [42880], [42971], [44786].

Props jrf.
See #59651.

[SergeyBiryukov]

In 57101:

Docs: Fix incorrect @return tag in wp_check_filetype() tests.

@return[] is not a valid tag. Fixed now, though without further specification.

Reference: ​PHP Documentation Standards: PHPDoc Tags.

Follow-up to [55456].

Props jrf.
See #59651.

[SergeyBiryukov]

In 57105:

Docs: Fix broken @covers tag in _wp_post_thumbnail_context_filter() tests.

Without the space between the tag and the "description", the tag will not be recognized and the test will not record coverage correctly.

Reference: ​PHPUnit Manual: Annotations.

Follow-up to [55821].

Props jrf.
See #59651.

[SergeyBiryukov]

In 57107:

Docs: Fix incorrect property doc in WP_Theme::get_allowed() tests.

The @array tag does not exist. This should be @var array.

Reference: ​PHP Documentation Standards: Class Members.

Follow-up to [36350].

Props jrf.
See #59651.

[SergeyBiryukov]

In 57108:

Docs: Replace miscellaneous incorrect PHPDoc tags.

• @contrib is not a valid tag.
• @origin is not a valid tag.
• @ref is not a valid tag.
• @blessed is not a valid tag and doesn't convey any meaningful information.
• @issue is not a valid tag.

Reference: ​PHP Documentation Standards: PHPDoc Tags.

Follow-up to [8852], [34754], [38832], [43808].

Props jrf.
See #59651.

Thanks for the PR! Merged in r57065, r57077, r57099, r57101, r57105, r57107, and r57108.

Thanks @SergeyBiryukov !

[dmsnell]

Replying to SergeyBiryukov:

In 57077:

Docs: Use proper case for @todo tags.

The correct tag is @todo, not @TODO or @todo: (note the trailing colon).

Reference: ​PHP Documentation Standards: PHPDoc tags.

Follow-up to [55203], [56274], [56565], [56698].

Props jrf.
See #59651.

@SergeyBiryukov do you have the corresponding update for Gutenberg already for this change?

[SergeyBiryukov]

In 57120:

Docs: Improve some DocBlocks and inline comments per the documentation standards.

Follow-up to [56834], [56836], [56837], [56838].

Props kebbet, costdev, mukesh27, SergeyBiryukov.
See #59651.

Thanks for the PR! Merged in r57120.

[SergeyBiryukov]

In 57121:

Docs: Fix typo in get_image_tag() DocBlock.

Follow-up to [54173].

Props kitchin.
See #55646, #59651.

[SergeyBiryukov]

In 57195:

Docs: Correct $wp_the_query global reference in WP_Query::is_main_query().

Follow-up to [18699], [32620], [34337], [45739].

See #59651.

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

[costdev]

In 57243:

Docs: Fix typo in twentyten_header_image_height filter's docblock.

This corrects a minor typo from "defaul" to "default" in the docblock of the twentyten_header_image_height filter.

Props mukesh27.
See #59651.

Committed in r57243.

[costdev]

In 57263:

Docs: Correct some typos in docblocks and inline comments.

This corrects several typos in documentation, including:

• "imput" -> "input"
• "proessing" -> "processing"
• "instantating" -> "instantiating"
• "filtersing" -> "filtering"
• "officaly" -> "officially"

Follow-up to [8852], [25307], [26191], [37488], [54416].

Props benniledl, mukesh27, jayadevankbh, Presskopp.
Fixes #60069. See #59651.

[audrasjb]

In 57280:

Docs: Fix wrong inline comment in delete_theme().

Props wildworks.
Fixes #60246.
See #59651.

[audrasjb]

In 57300:

Bundled Themes: Typo corrections in various themes docblocks.

Props shailu25.
Fixes #60268.
See #59651.

[audrasjb]

In 57302:

Docs: Fix var types of parameters in sanitize_option() and sanitize_option_{$option}.

The related docblocks were previously defining $value and $original_value as if they were of type string, but they can also be of other types, like array.

Props gerardreches, crstauf, mukesh27.
Fixes #60214.
See #59651.

[SergeyBiryukov]

In 57325:

Docs: Correct the WP_User Query location reference in query cache tests.

Follow-up to [1047/tests], [33749], [55657].

See #59651.

[SergeyBiryukov]

In 57349:

Docs: Fix typo in _get_block_template_file() DocBlock.

Follow-up to [55744].

See #59651.

[audrasjb]

In 57370:

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

Props upadalavipul, audrasjb, shailu25, viralsampat.
Fixes #59255.
See #59651.

[johnbillion]

In 57643:

REST API: Clarify documentation for methods and filters relating to REST API search endpoints.

See #59651

[johnbillion]

In 57644:

Docs: Various improvements and corrections to inline documentation.

See #59651

[swissspidy]

In 57692:

Docs: Use more inclusive term in rest_filter_response_fields docblock.

See #59651.

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

### Proper case for @todo tags
Valid: @todo

[audrasjb]

In 57774:

Docs: Add missing @global mention in wp_interactivity().

This merges a changeset updated upstream in the Gutenberg repository.
See ​https://github.com/WordPress/gutenberg/pull/59522.

Props wildworks.
Fixes #60677.
See #59651.

[swissspidy]

Closing for now since 6.5 has been branched, so any new updates like this can happen in trunk for 6.6.