Make WordPress Core

Opened 9 years ago

Closed 9 years ago

Last modified 8 years ago

#42901 closed defect (bug) (fixed)

All summary tags should be removed from existing JSDoc.

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

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 9 years ago.
jsdoc-no-summaries.2.patch​ (81.9 KB ) - added by herregroen 9 years ago.

Download all attachments as: .zip

Change History (8)

#1 @netweb
9 years ago

  • Focuses coding-standards added
  • Keywords has-patch added
  • Milestone Awaiting Review → 5.0
  • Version trunk

#2 @netweb
9 years ago

  • Keywords commit added

Reviewed, this is good to go in 👍🏼

#3 @herregroen
9 years ago

Updated patch to be compatible with newest trunk.

#4 @atimmer
9 years ago

  • Owner set to atimmer
  • Resolution → fixed
  • Status new → 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.


9 years ago

#6 @johnbillion
8 years ago

  • Milestone 5.0 → 5.1
Note: See TracTickets for help on using tickets.