[wp-trac] [WordPress Trac] #41682: JSDoc correction for namespaces
WordPress Trac
noreply at wordpress.org
Fri Aug 25 13:30:45 UTC 2017
#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
More information about the wp-trac
mailing list