[wp-trac] [WordPress Trac] #41682: JSDoc correction for namespaces

[WordPress Trac]

#41682: JSDoc correction for namespaces
--------------------------+-------------------------------
 Reporter:  herregroen    |       Owner:  adamsilverstein
     Type:  defect (bug)  |      Status:  assigned
 Priority:  normal        |   Milestone:  4.9
Component:  General       |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  has-patch     |     Focuses:  javascript, docs
--------------------------+-------------------------------

Comment (by netweb):

 Replying to [comment:18 herregroen]:
 > JSDoc matches documentation with the line exactly below it.
 >
 > The comment blocks at the top of files were documenting the var
 declarations, not the class declaration. This means that the comment block
 was documenting a class called `Controller` which has no methods or
 members of it's own. That's clearly not the intent.
 >
 > This ties in with the Wordpress Javascript documentation standards
 leading to errors. A documentation block containing `@class` should be
 directly above the class declaration. If the intent is to add a comment
 block to the top of a file to document what the file contains then this
 should be done with using `@file`.

 Perfect, thanks for the detailed reply +1

 > If JSHint or ESLint want documentation blocks at the top of files then
 these can be added but they should only contain the `@file` tag and
 possible the `@author` tag, there should be no other tags.

 +1 Let's look at doing this after this has been merged in a new ticket

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