Make WordPress Core

Opened 3 years ago

Last modified 3 years ago

#53875 new defect (bug)

Update inline docs to match handbook standards

Reported by: johnjamesjacoby's profile johnjamesjacoby Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: General Keywords:
Focuses: docs Cc:

Description (last modified by johnjamesjacoby)

While looking at #53399, relative to the 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

Change History (3)

#1 @johnjamesjacoby
3 years ago

  • Description modified (diff)

#2 @johnjamesjacoby
3 years ago

  • Description modified (diff)

#3 @sabernhardt
3 years ago

  • Milestone changed from Awaiting Review to Future Release

If we follow the single-line style, those comments could be full sentences:

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

If this would include the wp-config-sample file, I think I prefer the multi-line style for any settings there that users would edit. Then the lines at the bottom could stand out better with the single-line style.

/* That's all, stop editing! Happy publishing. */

// Define absolute path to the WordPress directory.
if ( ! defined( 'ABSPATH' ) ) {
	define( 'ABSPATH', __DIR__ . '/' );
}

// Set up WordPress vars and included files.
require_once ABSPATH . 'wp-settings.php';
Note: See TracTickets for help on using tickets.