Make WordPress Core

Opened 7 years ago

Closed 7 years ago

Last modified 6 years ago

#42901 closed defect (bug) (fixed)

All summary tags should be removed from existing JSDoc.

Reported by: herregroen's profile herregroen Owned by: atimmer's profile atimmer
Milestone: 5.1 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch commit
Focuses: javascript, docs, coding-standards Cc:

Description

The WordPress javascript documentation standards were recently changed in how to deal with short and long descriptions.

This includes no longer using the @summary tag. Instead a doc block should start with a short description and, optionally, include a longer description separated by an empty line.

Attachments (2)

jsdoc-no-summaries.patch (82.1 KB) - added by herregroen 7 years ago.
jsdoc-no-summaries.2.patch (81.9 KB) - added by herregroen 7 years ago.

Download all attachments as: .zip

Change History (8)

#1 @netweb
7 years ago

  • Focuses coding-standards added
  • Keywords has-patch added
  • Milestone changed from Awaiting Review to 5.0
  • Version trunk deleted

#2 @netweb
7 years ago

  • Keywords commit added

Reviewed, this is good to go in 👍🏼

#3 @herregroen
7 years ago

Updated patch to be compatible with newest trunk.

#4 @atimmer
7 years ago

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

In 42411:

Docs: Remove @summary tags from JSDoc.

As decided in the JavaScript core chat. With a few reasons:

  • It is visually cleaner when reading the source.
  • This bring the JavaScript documentation closer to the PHP documentation.

The only disadvantage is that the JSDoc parser doesn't split out the summary and the description in the new format. We've decided to solve this when building the JavaScript documentation parser.

Props herregroen.
Fixes #42901.

This ticket was mentioned in Slack in #core-js by aduth. View the logs.


7 years ago

#6 @johnbillion
6 years ago

  • Milestone changed from 5.0 to 5.1
Note: See TracTickets for help on using tickets.