[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       |  Resolution:
 Keywords:               |     Focuses:  javascript, docs
-------------------------+-------------------------------

Comment (by 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

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