Use eslint-plugin-jsdoc

[gajus]

Consider using eslint-plugin-jsdoc to enforce a specific style of JSDoc comments.

I propose the standard setup:

{
    "rules": {
        "jsdoc/check-param-names": 1,
        "jsdoc/check-redundant-params": 1,
        "jsdoc/check-redundant-returns": 1,
        "jsdoc/require-return-types": 1,
        "jsdoc/newline-after-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-param-description": 1,
        "jsdoc/require-param-types": 1,
        "jsdoc/require-return-types": 1
    }
}

[rstacruz]

I'm just concerned that not everyone uses jsdoc for /** ... */ comments.

[feross]

If this forces all users to use JSDoc comments, then it's a non starter. How does this behave for /** ... */ comments that aren't JSDoc?

[feross]

Also, what is the performance hit of adding this?

[gajus]

I'm just concerned that not everyone uses jsdoc for /** ... */ comments.

What are the variations?

Isn't the point of "standard" package to standardise the code style?

Whether JSDoc (comments) include code or not, is another question. Though having consistent comment blocks across different projects make reading code easier.

[feross]

The point is that lots of people use block comments to write comments that span multiple lines. It's not okay to force those to all be JSDoc.

[gajus]

The point is that lots of people use block comments to write comments that span multiple lines. It's not okay to force those to all be JSDoc.

Please include examples whenever describing use scenarios.

[gajus]

Please include examples whenever describing use scenarios.

It takes you to think of one example and write it down. When example is not included, it requires that every participant thinks of their own example and these examples are not necessarily the same. Does not help to the discussion.

[feross]

/**
 *  This is a block comment. This is not JSDoc.
 */

[gajus]

This is perfectly valid JSDoc comment block. It just does not have property definitions.

[Flet]

It might be interesting to run these rules via clone.js to see what issues might come up.

[feross]

It looks like adding this plugin would add dependencies on jscs and lodash. We're not adding back the jscs dependency since it took a lot of work to get to one linter (#45)

jscs alone requires all these packages and we're trying to make the install faster (#340)

- commander@2.9.0 node_modules/jscs/node_modules/commander
- esprima@2.7.0 node_modules/jscs/node_modules/esprima
- estraverse@4.1.1 node_modules/jscs/node_modules/estraverse
- babel-jscs@2.0.5 node_modules/babel-jscs
- cli-table@0.3.1 node_modules/cli-table
- colors@1.0.3 node_modules/colors
- comment-parser@0.3.0 node_modules/comment-parser
- cycle@1.0.3 node_modules/cycle
- exit@0.1.2 node_modules/exit
- eyes@0.1.8 node_modules/eyes
- has-color@0.1.7 node_modules/has-color
- i@0.3.3 node_modules/i
- is-utf8@0.2.0 node_modules/is-utf8
- jscs@2.6.0 node_modules/jscs
- jscs-jsdoc@1.2.0 node_modules/jscs-jsdoc
- jscs-preset-wikimedia@1.0.0 node_modules/jscs-preset-wikimedia
- jsdoctypeparser@1.2.0 node_modules/jsdoctypeparser
- jsonlint@1.6.2 node_modules/jsonlint
- JSV@4.0.2 node_modules/JSV
- natural-compare@1.2.2 node_modules/natural-compare
- ncp@0.4.2 node_modules/ncp
- nomnom@1.8.1 node_modules/nomnom
- ansi-styles@1.0.0 node_modules/nomnom/node_modules/ansi-styles
- chalk@0.4.0 node_modules/nomnom/node_modules/chalk
- strip-ansi@0.1.1 node_modules/nomnom/node_modules/strip-ansi
- underscore@1.6.0 node_modules/nomnom/node_modules/underscore
- pathval@0.1.1 node_modules/pathval
- pkginfo@0.3.1 node_modules/pkginfo
- prompt@0.2.14 node_modules/prompt
- read@1.0.7 node_modules/read
- reserved-words@0.1.1 node_modules/reserved-words
- revalidator@0.1.8 node_modules/revalidator
- stack-trace@0.0.9 node_modules/stack-trace
- strip-bom@2.0.0 node_modules/strip-bom
- utile@0.2.1 node_modules/utile
- vow@0.4.11 node_modules/vow
- vow-fs@0.3.4 node_modules/vow-fs
- glob@4.5.3 node_modules/vow-fs/node_modules/glob
- minimatch@2.0.10 node_modules/vow-fs/node_modules/minimatch
- vow-queue@0.4.2 node_modules/vow-queue
- winston@0.8.3 node_modules/winston
- colors@0.6.2 node_modules/winston/node_modules/colors
- xmlbuilder@3.1.0 node_modules/xmlbuilder

[gajus]

Just in case, we are working on removing the JSCS dependency. Will update when it is removed.

[gajus]

@feross JSCS has been removed as a dependency from v2.