jscs-jsdoc
Advanced tools
jsdoc plugin for jscs. Twitter | Mailing List
jscs-jsdoc can be installed using NPM and requires jscs.
Install it globally if you are using globally installed jscs
npm -g install jscs-jsdoc
But better install it into your project
npm install jscs-jsdoc --save-dev
We recommend installing jscs-jsdoc via NPM using ^, or ~ if you want more stable releases.
Semver (http://semver.org/) dictates that breaking changes be major version bumps. In the context of a linting tool, a bug fix that causes more errors to be reported can be interpreted as a breaking change. However, that would require major version bumps to occur more often than can be desirable. Therefore, as a compromise, we will only release bug fixes that cause more errors to be reported in minor versions.
Below you fill find our versioning strategy, and what you can expect to come out of a new jscs-jsdoc release.
jscs-jsdoc to report less errors;jscs-jsdoc to report more errors;To use plugin you should add these lines to configuration file .jscsrc:
{
"plugins": [
"jscs-jsdoc"
],
"jsDoc": {
"checkAnnotations": "closurecompiler",
"checkTypes": "strictNativeCase",
"enforceExistence": "exceptExports"
}
}
Ensures tag names are valid
There are 3 presets for Closure Compiler, JSDoc3 and JSDuck5.
By default it allows any tag of mixed set. You can pass Object to select preset with preset field and add custom tags with extra field.
Type: Boolean or String or {"preset": String, "extra": Object} (see tag values)
Values: true, "closurecompiler", "jsdoc3", "jsduck5", Object
Context: file
Tags: *
extra field should contains tags in keys and there are options for values:
false means tag available with no valuetrue means tag available with any value"some" means tag available and requires some valueSee also tag presets.
"checkAnnotations": true
/**
* @chainable
* @param {string} message
* @return {string}
*/
function _f() {}
/**
* @pororo
* @lalala
*/
function _f() {}
"checkAnnotations": {
"preset": "jsdoc3",
"extra": {
"boomer": false
}
}
/**
* @boomer
* @argument {String}
*/
function _f() {}
/** @still-invalid */
Ensures param names in jsdoc and in function declaration are equal
Type: Boolean
Values: true
Context: functions
Tags: param, arg, argument
"checkParamNames": true
/**
* @param {String} message
* @param {Number|Object} [line]
*/
function method(message, line) {}
/**
* @param {String} msg
* @param {Number|Object} [line]
*/
function method(message) {}
Ensures params in jsdoc contains type
Type: Boolean
Values: true
Context: functions
Tags: param, arg, argument
"requireParamTypes": true
/**
* @param {String} message
*/
function method() {}
/**
* @param message
*/
function method() {}
Reports redundant params in jsdoc
Type: Boolean
Values: true
Context: functions
Tags: param, arg, argument
"checkRedundantParams": true
/**
* @param {String} message
*/
function method(message) {}
/**
* @param {String} message
*/
function method() {}
Reports discrepancies between the claimed in jsdoc and actual type if both exist (code scan)
Type: Boolean
Values: true
Context: functions
Tags: return, returns
"checkReturnTypes": true
/**
* @returns {String}
*/
function method() {
return 'foo';
}
/**
* @returns {String}
*/
function method(f) {
if (f) {
return true;
}
return 1;
}
Report statements for functions with no return
Type: Boolean
Values: true
Context: functions
Tags: return, returns
"checkRedundantReturns": true
/**
* @returns {string}
*/
function f() {
return 'yes';
}
/**
* @returns {string}
*/
function f() {
// no return here
}
Ensures returns in jsdoc contains type
Type: Boolean
Values: true
Context: functions
Tags: return, returns
"requireReturnTypes": true
/**
* @returns {String}
*/
function method() {}
/**
* no @return
*/
function method() {}
/**
* @returns
*/
function method() {}
Reports invalid types for bunch of tags
In strictNativeCase mode ensures that case of natives is the same as in this list: boolean, number, string, Object, Array, Date, RegExp.
In capitalizedNativeCase mode ensures that first letter in all native types and primitives is uppercased except the case with function in google closure format: {function(...)}
Type: Boolean or String
Values: true or "strictNativeCase" or "capitalizedNativeCase"
Context: *
Tags: typedef, type, param, return, returns, enum, var, prop, property, arg, argument, cfg, lends, extends, implements, define
"checkTypes": true
/**
* @typedef {Object} ObjectLike
* @property {boolean} hasFlag
* @property {string} name
*/
/** @type {number} */
var bar = 1;
/** @const {number} */
var FOO = 2;
/**
* @const
* @type {number}
*/
var BAZ = 3;
/**
* @param {SomeX} x
* @returns {string}
*/
function method(x) {}
/** @type {some~number} */
var x = 1;
/**
* @param {function(redundantName: Number)} x
*/
function method(x) {}
/**
* @param {Number|Boolean|object|array} x invalid for strictNativeCase
*/
function method(x) {}
/** @type {some~number} */
var x = 1;
Reports redundant access declarations
Type: Boolean or String
Values: true or "enforceLeadingUnderscore" or "enforceTrailingUnderscore"
Context: functions
Tags: access, private, protected, public
"checkRedundantAccess": true
"checkRedundantAccess": "enforceLeadingUnderscore"
/**
* @access private
*/
function _f() {}
/**
* @access public
*/
function f() {}
/**
* @private
* @access private
*/
function _f() {}
/**
* @private
*/
function _f() {}
Ensures access declaration is set for _underscored function names
Ignores a bunch of popular identifiers: __filename, __dirname, __proto__, __defineGetter__, super_, __constructor, etc.
Type: Boolean or String
Values: true (means not public), "private", "protected"
Context: functions
Tags: access, private, protected, public
"leadingUnderscoreAccess": "protected"
/**
* @protected
*/
function _f() {}
function _g() {}
/**
* @private
*/
function _e() {}
Ensures jsdoc block exist
Type: Boolean or String
Values: true or "exceptExports" (skip module.exports = function () {};)
Context: functions
"enforceExistence": true
/**
* @protected
*/
function _f() {}
function _g() {}
Ensures a param description has a hyphen before it (checks for - )
Type: Boolean
Values: true
Context: functions
Tags: param, arg, argument
"requireHyphenBeforeDescription": true
/**
* @param {String} - message
*/
function method() {}
/**
* @param {String} message
*/
function method() {}
Ensures a doc comment description has padding newline
Type: Boolean
Values: true
Context: functions
Tags: *
"requireNewlineAfterDescription": true
/**
* @param {String} - message
*/
function method() {}
/**
* Description
*/
function method() {}
/**
* Description
*
* @param {String} - message
*/
function method() {}
/**
* Description
* @param {String} message
*/
function method() {}
Ensures a doc comment description has no padding newlines
Type: Boolean
Values: true
Context: functions
Tags: *
"disallowNewlineAfterDescription": true
/**
* @param {String} - message
*/
function method() {}
/**
* Description
*/
function method() {}
/**
* Description
* @param {String} - message
*/
function method() {}
/**
* Description
*
* @param {String} message
*/
function method() {}
Ensures a doc comment description is a complete sentence.
A complete sentence is defined as starting with an upper case letter and ending with a period.
Type: Boolean
Values: true
Context: functions
Tags: *
"requireDescriptionCompleteSentence": true
/**
* @param {String} - message
*/
function method() {}
/**
* Description.
*/
function method() {}
/**
* Description.
*
* @param {String} - message
*/
function method() {}
/**
* Description
* On multiple lines.
*
* @param {String} - message
*/
function method() {}
/**
* Description
* @param {String} message
*/
function method() {}
/**
* description starting with a lower case letter.
* @param {String} message
*/
function method() {}
/**
* Description period is offset .
* @param {String} message
*/
function method() {}
/**
* Description!
* @param {String} message
*/
function method() {}
Ensures a param description exists.
Type: Boolean
Values: true
Context: functions
Tags: param, arg, argument
"requireParamDescription": true
/**
* @param {String} arg message
*/
function method(arg) {}
/**
* @param arg message
*/
function method(arg) {}
##### Invalid
```js
/**
* @param {String} arg
*/
function method(arg) {}
/**
* @param arg
*/
function method(arg) {}
NOT SUPPORTED ATM. SORRY.
File jscs-jsdoc-browser.js contains browser-compatible version of jscs-jsdoc.
Download and include jscs-jsdoc-browser.js into your page just after jscs-browser.js.
<script src="jscs-browser.js"></script>
<script src="jscs-jsdoc-browser.js"></script>
<script>
var checker = new JscsStringChecker();
checker.registerDefaultRules();
checker.configure({'jsDoc': {/* ... */}});
var errors = checker.checkString('var x, y = 1;');
errors.getErrorList().forEach(function (error) {
console.log(errors.explainError(error));
});
</script>
[v1.1.0] - 2015-06-24
152ab67a91] - New rule: requireDescriptionCompleteSentence (dtracers)bf19a6c34c] - New rule: requireParamDescription (dtracers)79e316c2f2] - leadingUnderscoreAccess: skip checking for overriden methods #114 (Alexej Yaroshevich)9e56f72b88] - Docs: Add requireDescriptionCompleteSentence to readme. (dtracers)a34608a22b] - Docs: update changelog, fix broken link (Alexej Yaroshevich)abce52aea2] - Docs: update changelog and fix url (Alexej Yaroshevich)262ce3f3c5] - Docs: add rule requireParamDescription (Alexej Yaroshevich)cf2aff91c2] - Misc: bump jsdoctypeparser to use new PEG parser (Alexej Yaroshevich)544cf7d7cb] - Misc: add changelog npm command (Alexej Yaroshevich)85fba47e7f] - requireParamTypes: Change if to early return format (dtracers)FAQs
JSCS jsdoc plugin
The npm package jscs-jsdoc receives a total of 30,015 weekly downloads. As such, jscs-jsdoc popularity was classified as popular.
We found that jscs-jsdoc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.