Context Navigation

← Previous Ticket
Next Ticket →

#59651 closed task (blessed) (fixed)

Docblock improvements for 6.5

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

Description

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)

Change History (34)

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

3 years 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.

3 years 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
3 years 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 3 years ago by jrf (next)

#4 @SergeyBiryukov
3 years ago

In 57062:

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

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

See #59651.

#5 @SergeyBiryukov
3 years 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: ↓ 14 @SergeyBiryukov
3 years 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
3 years 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
3 years 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
3 years 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
3 years 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
3 years 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:

3 years ago #12

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

@jrf commented on PR #5585:

3 years ago #13

Thanks @SergeyBiryukov !

#14 in reply to: ↑ 6 @dmsnell
3 years 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
3 years 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:

3 years ago #16

Thanks for the PR! Merged in r57120.

#17 @SergeyBiryukov
3 years ago

In 57121:

Docs: Fix typo in get_image_tag() DocBlock.

Follow-up to [54173].

Props kitchin.
See #55646, #59651.

#18 @SergeyBiryukov
3 years 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.

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

3 years ago #19

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

#20 @costdev
3 years 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:

3 years ago #21

Committed in r57243.

#22 @costdev
3 years 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
3 years ago

In 57280:

Docs: Fix wrong inline comment in delete_theme().

Props wildworks.
Fixes #60246.
See #59651.

#24 @audrasjb
3 years ago

In 57300:

Bundled Themes: Typo corrections in various themes docblocks.

Props shailu25.
Fixes #60268.
See #59651.

#25 @audrasjb
3 years 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.