[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 herregroen):

 Replying to [comment:16 netweb]:
 > Why are variables being moved to the top of the file? Does JSDoc require
 this for formatting?
 >
 > There's quite a few instances of this, for example:
 >
 > {{{
 > #!diff
 > Index: src/wp-includes/js/media/controllers/customize-image-cropper.js
 > ===================================================================
 > --- src/wp-includes/js/media/controllers/customize-image-cropper.js
 (revision 41309)
 > +++ src/wp-includes/js/media/controllers/customize-image-cropper.js
 (working copy)
 > @@ -1,6 +1,11 @@
 > +var Controller = wp.media.controller,
 > +     CustomizeImageCropper;
 > +
 >  /**
 >   * wp.media.controller.CustomizeImageCropper
 >   *
 > + * @memberOf wp.media.controller
 > + *
 >   * A state for cropping an image.
 >   *
 >   * @class
 > @@ -8,10 +13,7 @@
 >   * @augments wp.media.controller.State
 >   * @augments Backbone.Model
 >   */
 > -var Controller = wp.media.controller,
 > -     CustomizeImageCropper;
 > -
 > -CustomizeImageCropper = Controller.Cropper.extend({
 > +CustomizeImageCropper = Controller.Cropper.extend(/** @lends
 wp.media.controller.CustomizeImageCropper.prototype */{
 >       doCrop: function( attachment ) {
 >               var cropDetails = attachment.get( 'cropDetails' ),
 >                       control = this.get( 'control' ),
 >
 > }}}
 >
 > Leaving the `var` declarations where they originally were doesn't cause
 any issue with linting via JSHint or the proposed ESLint changes we're in
 the progress of implementing

 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`.

 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.

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