Improve the Javascript Documentation Standards.

[herregroen]

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.

[herregroen]

Proposal for the new documentation standards.

[jdgrimes]

A couple small things I noticed as I was looking over the patch:

• At the start where it says "Short descriptions should be clear, simple, and brief. Document “what” and “when” – “why” should rarely need to be included." I think it would make sense to add "(the "why" can go in the long description if needed)."
• The Long descriptions section has an unfinished sentence at the end: "Markdown can be used, if needed, in a long description. Lines should be"

+1 on the comment alignment. It is also great to see the errors in how @param is used finally get fixed.

The guidance for Backbone will also be very helpful when I get around to documenting the JS in my plugin that uses Backbone. :-D

[atimmer]

I've changed ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/ to reflects these changes.

[netweb]

Thanks for updating the docs @atimmer and thanks @herregroen for the "patch".

Adding this to the 5.0 milestone and marking as fixed.