[wp-trac] [WordPress Trac] #53875: Update inline docs to match handbook standards

[WordPress Trac]

#53875: Update inline docs to match handbook standards
-----------------------------+-----------------------------
 Reporter:  johnjamesjacoby  |      Owner:  (none)
     Type:  defect (bug)     |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  General          |    Version:
 Severity:  normal           |   Keywords:
  Focuses:  docs             |
-----------------------------+-----------------------------
 While looking at #53399, relative to the
 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/php/#5-inline-comments PHP Documentation
 Standards], there are many-many places in the codebase that use PHP's
 multi-line code commenting style for what have always been (and likely
 always will be) single-line comments.

 For example:

 From `options-general.php`:
 {{{
 /** WordPress Administration Bootstrap */
 require_once __DIR__ . '/admin.php';

 /** WordPress Translation Installation API */
 require_once ABSPATH . 'wp-admin/includes/translation-install.php';
 }}}

 Further emphasis is put on not using `/**` specifically:

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

 According to our own standard, I believe these lines should instead be:

 {{{
 // WordPress Administration Bootstrap
 require_once __DIR__ . '/admin.php';

 // WordPress Translation Installation API
 require_once ABSPATH . 'wp-admin/includes/translation-install.php';
 }}}

 ...or possibly...

 {{{
 /* WordPress Administration Bootstrap */
 require_once __DIR__ . '/admin.php';

 /* WordPress Translation Installation API */
 require_once ABSPATH . 'wp-admin/includes/translation-install.php';
 }}}

 (My personal preference would be `// ..` over `/* .. */` because I find it
 easier to both type and read.)

 Starting this ticket (with a nod from @johnbillion) to generate some
 discussion and come to an agreement.

 ----

 For additional context, the examples I used above also use inconsistent
 language across the entire codebase, and my plan is to modify these lines
 already to make them consistent, and I'd like to bring both the syntax and
 the language inline together at the same time.

 `/** WordPress Administration Bootstrap */`

 `/** Load WordPress Administration Bootstrap */`

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