Make WordPress Core

Opened 9 months ago

Closed 6 months ago

Last modified 5 months ago

#58833 closed task (blessed) (fixed)

Docblock improvements for 6.4

Reported by: mukesh27's profile mukesh27 Owned by:
Milestone: 6.4 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch has-unit-tests
Focuses: docs, coding-standards Cc:

Description

Previously:

Change History (38)

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


8 months ago
#1

  • Keywords has-patch has-unit-tests added

In 434 cases, in the WP code a comment about PHPCS is used. In 424 cases, this is written like

phpcs:*

Yet, in ten cases... the first space is forgotten. In this PR, I want to improve that. Since this is imo a doc block improvement, I'm going to attach the Trac ticket for doc block improvements for 6.4

#2 @NekoJonez
8 months ago

Found ten cases in the WP code where, for PHPCS comments, a space was forgotten. In the above PR I change those.

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


8 months ago
#3

I found that the sentence in this doc flows weird... It's as if there is a verb missing.

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

This ticket was mentioned in Slack in #core by nekojonez. View the logs.


8 months ago

#5 @SergeyBiryukov
8 months ago

In 56397:

Docs: Fix typo in duplicate hook references for views_{$this->screen->id}.

Follow-up to [29218], [29625].

Props nithins53, NekoJonez, mukesh27.
Fixes #59102. See #58833.

#6 @johnbillion
8 months ago

In 56414:

Docs: Miscellaneous docblock corrections and improvements.

See #58833

#7 @johnbillion
8 months ago

In 56415:

REST API: Correct the docblocks for various permission related methods.

See #58833

#8 @johnbillion
8 months ago

In 56416:

Media: Standardise documentation of the $crop parameter for various media functions and methods.

See #58833

#9 @SergeyBiryukov
8 months ago

In 56418:

Docs: Correct punctuation in some instances of the $crop parameter description.

Follow-up to [56416].

See #58833.

#10 @audrasjb
8 months ago

In 56433:

Docs: Add missing @param description in WP_Comment class.

Props armondal, hztyfoon, SergeyBiryukov.
Fixes #58890.
See #58833.

@audrasjb commented on PR #5010:


8 months ago
#11

It looks understandable on my side so I'd say it's ok to keep it as it is, but I'm not a native English speaker.
By the way there is another occurrence just above this hook.

#12 @audrasjb
8 months ago

In 56434:

Docs: Wrap inline @see tags in curly braces.

Props costdev, mukesh27.
Fixes #58858.
See #58833.

#13 @audrasjb
8 months ago

In 56435:

Docs: Use third-person singular verbs in various function descriptions, as per docblocks standards.

See #58833.

#14 @audrasjb
8 months ago

In 56436:

Docs: Clarify post_date_column_time filter description.

Props crstauf, mukesh27.
Fixes #59029.
See #58833.

#15 @audrasjb
8 months ago

In 56441:

Docs: Correct default post type in page_template_dropdown() docblock.

The default post type used by page_template_dropdown() is page, not post.

Props maxinacube.
Fixes #58972.
See #58833.

#16 @audrasjb
8 months ago

In 56471:

Docs: Docblock improvements in _deprecated_class() function, as per docblocks standards.

Follow-up to [56467].

See #58833.

#17 @audrasjb
8 months ago

In 56472:

Docs: Improve PHPCS comments general consistency.

Props nekojonez.
See #58833.

#19 @SergeyBiryukov
8 months ago

In 56474:

Docs: Fix typo in a translator comment in _deprecated_class().

Includes a few other formatting adjustments for consistency.

Follow-up to [48327], [56467], [56471].

See #58833.

#20 @johnbillion
8 months ago

In 56476:

Database: Improve the documentation for various methods in the wpdb class.

See #58833

#21 @johnbillion
8 months ago

In 56482:

Privacy: Improve docblocks for hooks and functions related to personal data export and erasure.

See #58833

#22 @kebbet
7 months ago

block_core_navigation_add_directives_to_submenu in /wp-includes/blocks/navigation.php says the parameter $w is a string, but the function treats it as an object. Should the docblock be updated in core or in the Gutenberg repo? Or is this correct?

@kebbet commented on PR #5304:


7 months ago
#24

Could you pleaase review @costdev @audrasjb ? Thanks!

#25 @SergeyBiryukov
7 months ago

In 56767:

Docs: Improve documentation for get_avatar() and related functions.

Includes:

  • Expanding and synchronizing documentation for the default and rating arguments.
  • Adding @since entries for the loading, fetchpriority, and decoding arguments.
  • Wrapping long lines as per the documentation standards.
  • Fixing a typo in the identicon value.
  • Minor formatting edits for consistency.

Follow-up to [31107], [45632], [47554], [53480], [56037].

See #58833.

#26 @SergeyBiryukov
7 months ago

In 56772:

Twenty Fourteen: Correct @since entry for an authors list query arguments filter.

Follow-up to [51943].

See #58833.

#27 @SergeyBiryukov
7 months ago

In 56774:

Docs: Use 3-digit, x.x.x style semantic versioning for two @since entries.

Follow-up to [41626], [56541].

See #58833.

#28 @costdev
6 months ago

In 56825:

Docs: Use US spelling and correct a typing mistake.

This changes two inline comments and a docblock so that they use US spelling as advised by the Core Handbook's Best Practices. A typing mistake is also corrected.

Reference:

Follow-up to [18632], [38120], [44954].

Props kebbet, mukesh27.
See #58833.

@costdev commented on PR #5304:


6 months ago
#30

Thanks for the PR! Merged in r56825.

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


6 months ago
#31

Fixing minor style issues in the comments, after 6.3.2.

https://core.trac.wordpress.org/ticket/58833

@kebbet commented on PR #5507:


6 months ago
#32

Please review @mukeshpanchal27 or @costdev :)

@kebbet commented on PR #5507:


6 months ago
#33

Agree on that, thank you for your comment and review Colin!

#34 @hellofromTonya
6 months ago

#59651 is now open for 6.5.

#35 @hellofromTonya
6 months ago

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

The RC1 release party is about to start. Closing this as fixed. Thank you everyone for your contributions :)

@kebbet commented on PR #5507:


6 months ago
#36

Please review and feel free to approve (and commit) if you have the time to do it @costdev !

@kebbet commented on PR #5507:


6 months ago
#37

Please review and feel free to approve (and commit) if you have the time to do it @costdev !

@SergeyBiryukov commented on PR #5507:


5 months ago
#38

Thanks for the PR! Merged in r57120.

Note: See TracTickets for help on using tickets.