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.
- Patch release:
- A bug fix in a rule that causes
jscs-jsdoc
to report less errors; - Docs, refactoring and other "invisible" changes for user;
- A bug fix in a rule that causes
- Minor release:
- Any preset changes;
- A bug fix in a rule that causes
jscs-jsdoc
to report more errors; - New rules or new options for existing rules that don't change existing behavior;
- Modifying rules so they report less errors, and don't cause build failures;
- Major release:
- Purposefully modifying existing rules so that they report more errors or change the meaning of a rule;
- Any architectural changes that could cause builds to fail.
To use plugin you should add these lines to configuration file .jscsrc
:
{
"additionalRules": [
"node_modules/jscs-jsdoc/lib/rules/*.js"
],
"jsDoc": {
"enforceExistence": true
}
}
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
Type: Boolean
Values: true
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;
Reports redundant access declarations
Type: Boolean
Values: true
Context: functions
Tags: access
, private
, protected
, public
"checkRedundantAccess": true
/**
* @access private
*/
function _f() {}
/**
* @private
* @access private
*/
function _f() {}
Ensures access declaration is set for _underscored
function names
Type: Boolean
or String
Values: true
(means not public), "private"
, "protected"
Context: functions
Tags: access
, private
, protected
, public
"checkRedundantAccess": "protected"
/**
* @protected
*/
function _f() {}
function _g() {}
/**
* @private
*/
function _e() {}
Ensures jsdoc block exist
Type: Boolean
Values: true
Context: functions
"enforceExistence": true
/**
* @protected
*/
function _f() {}
function _g() {}
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>