[wp-trac] [WordPress Trac] #56582: Decide how to format multi-line comments in global scope.

[WordPress Trac]

#56582: Decide how to format multi-line comments in global scope.
------------------------------------+-----------------------------
 Reporter:  costdev                 |      Owner:  (none)
     Type:  enhancement             |     Status:  new
 Priority:  normal                  |  Milestone:  Awaiting Review
Component:  General                 |    Version:
 Severity:  normal                  |   Keywords:
  Focuses:  docs, coding-standards  |
------------------------------------+-----------------------------
 [https://developer.wordpress.org/coding-standards/inline-documentation-
 standards/php/ The PHP Documentation Standards] include formats for
 various types of comment.

 However, there is no clear description of what to use for multi-line
 comments in global scope.

 For example:

  **3. Requires and Includes**
  Files required or included should be documented with a summary
 description DocBlock.
  Optionally, this may apply to inline `get_template_part()` calls as
 needed for clarity.

 However:

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

  **5.2 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.
      */
  }}}
  **Important note:** Multi-line comments must not begin with `/**` (double
 asterisk) as the parser might mistake it for a DocBlock. Use `/*` (single
 asterisk) instead.

 Note: It's quite possible that the inline multi-line format just never
 expected to have to cover multi-line comments in global scope and was too
 specific in saying "inside methods and functions".

 This leads to inconsistent formats and unnecessary discussion about what
 is correct.

 Let's decide on a format that is appropriate.

 Should we use `/**`, which is described for other items in global scope,
 or, as this format typically denotes something extra important (such as
 requires/includes, docblocks, class members, pre-existing filter
 docblocks), should we instead use the already existing multi-line comment
 format of `/*`?

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