Make WordPress Core

Opened 9 months ago

Closed 4 months ago

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


9 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.


9 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
9 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.

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.

Last edited 9 months ago by jrf (previous) (diff)

#4 @SergeyBiryukov
8 months ago

In 57062:

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

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

See #59651.

#5 @SergeyBiryukov
8 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
8 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
8 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
8 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
8 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
8 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
8 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:


8 months ago
#12

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

@jrf commented on PR #5585:


8 months ago
#13

Thanks @SergeyBiryukov !

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


8 months ago
#16

Thanks for the PR! Merged in r57120.

#17 @SergeyBiryukov
8 months ago

In 57121:

Docs: Fix typo in get_image_tag() DocBlock.

Follow-up to [54173].

Props kitchin.
See #55646, #59651.

#18 @SergeyBiryukov
7 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
6 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:


6 months ago
#21

Committed in r57243.

#22 @costdev
6 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
6 months ago

In 57280:

Docs: Fix wrong inline comment in delete_theme().

Props wildworks.
Fixes #60246.
See #59651.

#24 @audrasjb
6 months ago

In 57300:

Bundled Themes: Typo corrections in various themes docblocks.

Props shailu25.
Fixes #60268.
See #59651.

#25 @audrasjb
6 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
6 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
6 months ago

In 57349:

Docs: Fix typo in _get_block_template_file() DocBlock.

Follow-up to [55744].

See #59651.

#28 @audrasjb
6 months ago

In 57370:

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

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

#29 @johnbillion
5 months ago

In 57643:

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

See #59651

#30 @johnbillion
5 months ago

In 57644:

Docs: Various improvements and corrections to inline documentation.

See #59651

#31 @swissspidy
5 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.


4 months ago
#32

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

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

#33 @audrasjb
4 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
4 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.