WordPress.org

Make WordPress Core

Opened 6 years ago

Closed 6 years ago

#30591 closed defect (bug) (fixed)

Convert nonstandard use of “(optional)” in @param DocBlocks

Reported by: coffee2code Owned by: DrewAPicture
Milestone: 4.1 Priority: low
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

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 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.

Attachments (2)

30591.diff (12.3 KB) - added by coffee2code 6 years ago.
Patch mentioned in ticket description.
30591-typo.diff (608 bytes) - added by TobiasBg 6 years ago.

Download all attachments as: .zip

Change History (6)

@coffee2code
6 years ago

Patch mentioned in ticket description.

#1 @DrewAPicture
6 years ago

  • Milestone changed from Awaiting Review to 4.1
  • Version 4.0.1 deleted

#2 @DrewAPicture
6 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 30753:

Convert various uses of (optional) in core parameter descriptions to use the style prescribed in the inline documentation standards for PHP.

The style for marking parameters optional in inline PHP docs is: @param type $var Optional. Description. Accepts. Default., where Accepts can be omitted on a case-by-case basis.

Props coffee2code.
Fixes #30591.

@TobiasBg
6 years ago

#3 @TobiasBg
6 years ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

30591-typo.diff fixes a typo in [30753].

#4 @DrewAPicture
6 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed

In 30755:

Fix a typo in the return description for get_sample_permalink().

Props TobiasBg.
Fixes #30591.

Note: See TracTickets for help on using tickets.