[wp-trac] [WordPress Trac] #42107: Improve the Javascript Documentation Standards.

[WordPress Trac]

#42107: Improve the Javascript Documentation Standards.
------------------------------+-----------------------------
 Reporter:  herregroen        |      Owner:
     Type:  enhancement       |     Status:  new
 Priority:  normal            |  Milestone:  Awaiting Review
Component:  General           |    Version:  trunk
 Severity:  normal            |   Keywords:
  Focuses:  javascript, docs  |
------------------------------+-----------------------------
 Currently the Javascript Documentation Standards (
 [https://make.wordpress.org/core/handbook/best-practices/inline-
 documentation-standards/javascript/] ) contain several errors ( for
 example, how the `@global` and `@param` tags are used ) and, given that a
 lot of Javascript involves the use of Backbone, a lack of examples on how
 to document Backbone classes.

 I've prepared a proposal for updated documentation standards with the
 following changes:

 Aligning comments
 * Added a section on aligning comments.

 Function documentation:
 * `@augments` should not list the chain of inheritance, JSDoc can resolve
 this automatically if parents are properly documented and if ancestors are
 listed later their methods will override those of direct parents.
 * Added `@alias`.
 * Added `@memberOf`.
 * Clarified `@fires` that it can optionally list a class name the event is
 tied to and corrected the example to use a hashtag.
 * Updated example of `@listens` for proper usage of the event namespace.
 * `@global` should not be used to list globals used. It should be used to
 mark the function as global.
 * Added examples of optional variables using `@param`.
 * Added examples of variables with default values using `@param`.

 Backbone class documentation
 * Added explanation and examples for documenting Backbone classes.

 Object properties
 * Changed to Class members as that seems to be what it's trying to
 explain. `@property` can not be used as shown.

 Namespaces
 * Added explanation and examples for documenting namespaces.

 Local functions and classes.
 * Added explanations and examples for documenting local functions and
 classes as inner members.

 File headers
 * Updated to use the `@file` and `@author` tags instead of the `@class`
 tag.
 * Removed tags that cannot be used in file headers.

 I would love to have more input for my proposal and see an eventual update
 to the current documentation standards to better aid those who wish to
 contribute with helpful explanations and examples.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/42107>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform