[wp-trac] [WordPress Trac] #30591: Convert nonstandard use of “(optional)” in @param DocBlocks

[WordPress Trac]

#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