Make WordPress Core

#59651 closed task (blessed) (fixed)

Docblock improvements for 6.5

Reported by: hellofromtonya's profile hellofromTonya Owned by:
Milestone: 6.5 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs, coding-standards Cc:

Description

Previously:

Change History (34)

This ticket was mentioned in PR #5507 on WordPress/wordpress-develop by @kebbet.


16 months ago
#1

  • Keywords has-patch added

Fixing minor style issues in the comments, after 6.3.2.

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

This ticket was mentioned in PR #5585 on WordPress/wordpress-develop by @jrf.


16 months ago
#2

  • Keywords has-unit-tests added

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

#3 @jrf
16 months ago

  • Keywords has-unit-tests removed

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

Issues discovered while testing a sniff I'm writing.

Version 0, edited 16 months ago by jrf (next)

#4 @SergeyBiryukov
15 months ago

In 57062:

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

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

See #59651.

#5 @SergeyBiryukov
15 months ago

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.

#6 follow-up: @SergeyBiryukov
15 months ago

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.

#7 @SergeyBiryukov
15 months ago

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.

#8 @SergeyBiryukov
15 months ago

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.

#9 @SergeyBiryukov
15 months ago

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.

#10 @SergeyBiryukov
15 months ago

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.

#11 @SergeyBiryukov
15 months ago

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.

@SergeyBiryukov commented on PR #5585:


15 months ago
#12

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

@jrf commented on PR #5585:


15 months ago
#13

Thanks @SergeyBiryukov !

#14 in reply to: ↑ 6 @dmsnell
15 months ago

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?

#15 @SergeyBiryukov
15 months ago

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.

@SergeyBiryukov commented on PR #5507:


15 months ago
#16

Thanks for the PR! Merged in r57120.

#17 @SergeyBiryukov
15 months ago

In 57121:

Docs: Fix typo in get_image_tag() DocBlock.

Follow-up to [54173].

Props kitchin.
See #55646, #59651.

#18 @SergeyBiryukov
14 months ago

In 57195:

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

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

See #59651.

#20 @costdev
13 months ago

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.

@costdev commented on PR #5823:


13 months ago
#21

Committed in r57243.

#22 @costdev
13 months ago

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.

#23 @audrasjb
13 months ago

In 57280:

Docs: Fix wrong inline comment in delete_theme().

Props wildworks.
Fixes #60246.
See #59651.

#24 @audrasjb
13 months ago

In 57300:

Bundled Themes: Typo corrections in various themes docblocks.

Props shailu25.
Fixes #60268.
See #59651.

#25 @audrasjb
13 months ago

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.

#26 @SergeyBiryukov
13 months ago

In 57325:

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

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

See #59651.

#27 @SergeyBiryukov
13 months ago

In 57349:

Docs: Fix typo in _get_block_template_file() DocBlock.

Follow-up to [55744].

See #59651.

#28 @audrasjb
13 months ago

In 57370:

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

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

#29 @johnbillion
12 months ago

In 57643:

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

See #59651

#30 @johnbillion
12 months ago

In 57644:

Docs: Various improvements and corrections to inline documentation.

See #59651

#31 @swissspidy
12 months ago

In 57692:

Docs: Use more inclusive term in rest_filter_response_fields docblock.

See #59651.

This ticket was mentioned in PR #6213 on WordPress/wordpress-develop by @huzaifaalmesbah.


11 months ago
#32

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

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

#33 @audrasjb
11 months ago

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.

#34 @swissspidy
11 months ago

  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.