Opened 3 years ago
Last modified 3 years ago
#53875 new defect (bug)
Update inline docs to match handbook standards
Reported by: | johnjamesjacoby | Owned by: | |
---|---|---|---|
Milestone: | Future Release | Priority: | normal |
Severity: | normal | Version: | |
Component: | General | Keywords: | |
Focuses: | docs | Cc: |
Description (last modified by )
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
If we follow the single-line style, those comments could be full sentences:
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.