Decide how to format multi-line comments in global scope.

[costdev]

​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 /*?

[sabernhardt]

Related: #53875

[dingo_d]

I'm in favor of following the ​PSR-5 standard. They are using /** for any kind of structural element (check the ​documentation for the description of a structural element definition).

Multiline comments (starting with just one \*) should be used for non-essential explanations inside the code (like inside the function body) IMO.