[wp-trac] [WordPress Trac] #58459: Replace multiple single line comments with multi-line comments

[WordPress Trac]

#58459: Replace multiple single line comments with multi-line comments
------------------------------------+-----------------------------------
 Reporter:  costdev                 |      Owner:  (none)
     Type:  enhancement             |     Status:  new
 Priority:  normal                  |  Milestone:  6.3
Component:  General                 |    Version:
 Severity:  normal                  |   Keywords:  2nd-opinion has-patch
  Focuses:  docs, coding-standards  |
------------------------------------+-----------------------------------
 == Overview

 The [https://developer.wordpress.org/coding-standards/inline-
 documentation-standards/php/#5-inline-comments 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 [https://make.wordpress.org/core/2022/11/24/proposal-amend-
 the-inline-documentation-standards-for-multi-line-comments/ 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

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/58459>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform