Replace multiple single line comments with multi-line comments

[costdev]

Overview

The ​PHP Inline Documentation Standards: Inline Comments section states:

Inline Comments
Inline comments inside methods and functions should be formatted as follows:

Single line comments

// Allow plugins to filter an array.

Multi-line comments

/*
 * This is a comment that is long enough to warrant being stretched over
 * the span of multiple lines. You'll notice this follows basically
 * the same format as the PHPDoc wrapping and comment block style.
 */

A proposal to ​amend the Inline Documentation Standards for multi-line comments didn't get support.

There are quite a lot of cases when this standard has not been met in Core. As more files contain non-compliant comments, this leads to more instances to maintain consistency, with an aim to address all instances at once in the future.

The future is here!

Approach

For most cases, multiple single line comments can just be replaced with the multi-line comment format. Others may be "unnecessary" line breaks which can be changed to one single line comment.

Caveats

1. The inline documentation standards state "inside methods and functions". Therefore, root-level use of multiple single line comments should not be changed. To change these would require a change to the standard, which is outside the scope of this ticket.
2. When PHPCS is enabled, disabled, or sniffs are ignored, these should not use the multi-line comment format.
3. As always, this excludes external libraries and files maintained in Gutenberg. Gutenberg-maintained files should be updated on the Gutenberg repository.

Related: #57839

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

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

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

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

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

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

[audrasjb]

Thanks @costdev! This looks good to me at a glance. I'll take more time for an in-depth review of each PR but BTW I'm wondering whether we should use this change to replace most verbs with third person singular…
​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#language

[costdev]

@audrasjb Thanks! I split the PRs into groups of 20 files to try to make the review process a bit smoother 🙂

The Language section states:

A function, hook, class, or method is a third-person singular element, meaning that third-person singular verbs should be used to describe what each does.

So I think the third-person singular verbs are just for those docblocks rather than inline comments, right?

We could certainly correct things like missing ., capitalization and typos on the touched comments. That way, we don't need to wait until someone just happens to spot those issues.

[costdev]

FWIW, I'm happy to follow up with another ticket that specifically looks at docblocks and ensures they use third-person singular verbs. I've seen many of your commits to that effect and I'd definitely like to check out any remaining instances and get those fixed up.

[audrasjb]

Alright, let's not jump the gun and strictly focus on the goal of this ticket 👍

[costdev]

@audrasjb What's your opinion on the best plan for when to commit this one?

My thinking:
Docs changes aren't a priority as we approach Beta 1, but I'm also thinking this is a sooner-the-better ticket to help avoid new instances being introduced as part of "consistent non-compliance" with the standard.

Depending on where the reviewing process is at, we may still be able to land the PRs soon (maybe even ahead of Beta 1?) and save time by not having to update the PRs with new instances introduced between now and commit.

[audrasjb]

Hey @costdev my plan is to commit this once beta 1 is released so most enhancement commits are done and we don't add conflicts to all the existing PRs, yeah 😅

[costdev]

Good point! 😂

[audrasjb]

In 56174:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56175:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174].

Props costdev, audrasjb.
See #58459.

Committed in https://core.trac.wordpress.org/changeset/56174
and https://core.trac.wordpress.org/changeset/56175

[audrasjb]

In 56176:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175].

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56177:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176].

Props costdev, audrasjb.
See #58459.

Committed in https://core.trac.wordpress.org/changeset/56176
and https://core.trac.wordpress.org/changeset/56177

[audrasjb]

In 56178:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177].

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56179:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178].

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56180:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179].

Props costdev, audrasjb.
See #58459.

Committed in https://core.trac.wordpress.org/changeset/56177, https://core.trac.wordpress.org/changeset/56178, and https://core.trac.wordpress.org/changeset/56179.

[audrasjb]

In 56191:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180].

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56192:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191].

Props costdev, audrasjb.
See #58459.

Committed in https://core.trac.wordpress.org/changeset/56191 and https://core.trac.wordpress.org/changeset/56192
I fixed the two conflicting files.

[audrasjb]

In 56193:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192].

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56194:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193].

Props costdev, audrasjb.
See #58459.

committed in 56193 and 56194

[audrasjb]

In 56195:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193], [56194].

Props costdev, audrasjb.
See #58459.

[audrasjb]

In 56196:

Docs: Replace multiple single line comments with multi-line comments.

This changeset updates various comments as per WordPress PHP Inline Documentation Standards.
See ​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments.

Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193], [56194], [56195].

Props costdev, audrasjb.
See #58459.

Committed in https://core.trac.wordpress.org/changeset/56195 and https://core.trac.wordpress.org/changeset/56196

[audrasjb]

And that's a wrap for WP 6.3!
Phew, what a journey or review/refresh/commit :D

Thanks for the patches @costdev :D

[costdev]

Thanks @audrasjb! At least any future ones should be reduced! xD

[audrasjb]

Sure thing! 🤙