[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           |  Resolution:
 Keywords:                   |     Focuses:  docs
-----------------------------+------------------------------
Description changed by johnjamesjacoby:

Old description:

> 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.
>
> Before:
>
> `/** WordPress Administration Bootstrap */`
>
> After:
> `// Load WordPress Administration Bootstrap`

New description:

 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';
 }}}

 The docs put emphasis 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.

 It's worth emphasizing here that it does not say ''single-line'' comments
 shouldn't use `/**` but the handbook docs do not explain (that I have
 found) when and why single-line comments should use `/**`. This same
 syntax is also used when hooks are used in multiple locations, for
 example.

 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.

 Before:

 `/** WordPress Administration Bootstrap */`

 After:
 `// Load WordPress Administration Bootstrap`

--

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