jscs-jsdoc

jscs-jsdoc

jsdoc plugin for jscs.

Friendly packages

• JSCS: https://github.com/jscs-dev/node-jscs/

Plugin installation

jscs-jsdoc can be installed using npm. 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

Usage

To use plugin you should add it to configuration file .jscsrc:

{
    "additionalRules": [
        "node_modules/jscs-jsdoc/lib/rules/*.js"
    ],
    "jsDoc": {
    }
}

Configuration

jsDoc

Enables JsDoc validation.

Type: Object

Values:

• "checkParamNames" ensures param names in jsdoc and in function declaration are equal
• "requireParamTypes" ensures params in jsdoc contains type
• "checkRedundantParams" reports redundant params in jsdoc
• "checkReturnTypes" tries to compare function result type with declared type in jsdoc
• "requireReturnTypes" ensures returns in jsdoc contains type
• "checkTypes" reports invalid types
• "checkRedundantReturns" reports redundant returns in jsdoc
• "checkRedundantAccess" reports redundant access declarations
• "leadingUnderscoreAccess" ensures access declaration is set for _underscored function names
• "enforceExistence" ensures jsdoc declarations exists for functions and methods

Example

"jsDoc": {
    "checkParamNames": true,
    "checkRedundantParams": true,
    "requireParamTypes": true,
    "checkReturnTypes": true,
    "requireReturnTypes": true,
    "checkTypes": true,
    "checkRedundantReturns": true,
    "checkRedundantAccess": true,
    "leadingUnderscoreAccess": "private",
    "enforceExistence": true
}

Valid

/**
 * Adds style error to the list
 *
 * @private
 * @param {String} message
 * @param {Number|Object} line
 * @param {Number} [column]
 * @returns {String[]}
 */
_add: function(message, line, column) {
    return ['foo', 'bar'];
}

Invalid

/**
 * Adds style error to the list
 *
 * @protected
 * @param {String} message
 * @param {Number,Object} line
 * @param {Number} [column]
 * @returns {String}
 */
_add: function() {
    if (true) {
        return false;
    }
    return 15;
}

Browser Usage

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>

Changelog

[v0.0.17] - 2014-11-10

Bug fixes

• [5c963e0142] - checkRedundantReturns: add test for issue #34 (Alexej Yaroshevich)
• [e794e86a31] - checkReturnTypes: add 'class' as valid custom object (Alexej Yaroshevich)
• [f74570c608] - checkTypes: split rule logic and add checkin for other typed tags (Alexej Yaroshevich)
• [593053c50d] - split returns to separated rules (Alexej Yaroshevich)
• [a3ecd830b7] - fix location issues in jsdoc and split param rules (Alexej Yaroshevich)

Misc

• [9ef4bcbf37] - split param tests to separated files (for simplicity) (Alexej Yaroshevich)
• [db9c731a8a] - reworking jsdoc-helpers, introducing jsdoctypeparser (Alexej Yaroshevich)
• [d360309965] - rules api refactoring (Alexej Yaroshevich)
• [165ed20dc4] - basic return rules: refactor tests (Alexej Yaroshevich)
• [d846a5b1da] - tests: fix linting directories to lib and test (Alexej Yaroshevich)