[wp-trac] [WordPress Trac] #30591: Convert nonstandard use of “(optional)” in @param DocBlocks
WordPress Trac
noreply at wordpress.org
Thu Dec 4 08:34:31 UTC 2014
#30591: Convert nonstandard use of “(optional)” in @param DocBlocks
--------------------------+-----------------------------
Reporter: coffee2code | Owner:
Type: defect (bug) | Status: new
Priority: low | Milestone: Awaiting Review
Component: General | Version: 4.0.1
Severity: normal | Keywords: has-patch
Focuses: docs |
--------------------------+-----------------------------
A number of @param DocBlock descriptions use "(optional)" to denote a
parameter as being optional. Additionally, its use is inconsistent,
sometimes appearing at the start of the parameter description and
sometimes at the end.
The [https://make.wordpress.org/core/handbook/inline-documentation-
standards/php-documentation-standards/#1-functions-and-class-methods
inline documentation standards] require that an optional parameter should
be denoted with "Optional." at the beginning of the description.
Attached patch corrects all existing occurrences of this nonstandard
notation.
Since those doc lines were changing anyway, I also went ahead and made
some very minor formatting tweaks to those modified lines and/or to
immediately adjacent lines. This includes: adding ending period for
descriptions, stating the default value if not done so, correcting the way
some default values were stated, aligning @param elements, and a few text
fixes.
--
Ticket URL: <https://core.trac.wordpress.org/ticket/30591>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform
More information about the wp-trac
mailing list