jscsrc: add jsdoc rules, fixup code

Author: Alexej Yaroshevich

.jscsrc

@@ -16,5 +16,20 @@
     "excludeFiles": [
       "test/data/**",
       "test/lib/rules/**"
-    ]
+    ],
+
+    "plugins": ["jscs-jsdoc"],
+
+    "jsDoc": {
+        "enforceExistence": true,
+        "checkAnnotations": "closurecompiler",
+        "checkParamNames": true,
+        "requireParamTypes": true,
+        "checkRedundantParams": true,
+        "checkReturnTypes": true,
+        "checkRedundantReturns": true,
+        "requireReturnTypes": true,
+        "checkTypes": "strictNativeCase",
+        "checkRedundantAccess": true
+    }
 }

lib/esprima-helpers.js

@@ -10,7 +10,8 @@ var scopeNodeTypes = [
 
 /**
  * Search for the closest scope node tree for Node
- * @param {{type: String}} n
+ * @param {{type: string}} n
+ * @returns {EsprimaNode}
  */
 function closestScopeNode (n) {
     while (n && scopeNodeTypes.indexOf(n.type) === -1) {

lib/index.js

@@ -1,3 +1,6 @@
+/**
+ * @param {module:jscs/lib/Configuration} configuration
+ */
 module.exports = function(configuration) {
     configuration.registerRule(require('./rules/validate-jsdoc'));
 };

lib/jsdoc.js

@@ -8,6 +8,7 @@ var TypeBuilder = require('jsdoctypeparser').Builder;
 TypeBuilder.ENABLE_EXCEPTIONS = true;
 
 module.exports = {
+
     /**
      * @param {string} commentNode
      * @returns {DocComment}
@@ -57,18 +58,18 @@ function DocComment(value, loc) {
     });
 
     /**
-     * @param {function} fn
-     * @chainable
+     * @param {function(this: DocComment, DocTag): DocComment} fn
+     * @returns {DocComment}
      */
     this.iterate = function forEachTag(fn) {
-        this.tags.forEach(fn);
+        this.tags.forEach(fn, this);
         return this;
     };
 
     /**
-     * @param {string|array} types
-     * @param {function} fn
-     * @chainable
+     * @param {string|Array.<string>} types
+     * @param {function(this: DocComment, DocTag): DocComment} fn
+     * @returns {DocComment}
      */
     this.iterateByType = function iterateByTypes(types, fn) {
         var k = 0;
@@ -85,7 +86,7 @@ function DocComment(value, loc) {
 
 /**
  * Simple jsdoc tag object
- * @param {Object} tag
+ * @param {Object} tag object from comment parser, fields: tag, line, value, name, type, description
  * @param {DocLocation} loc
  * @constructor
  */
@@ -159,8 +160,8 @@ function DocType(type, loc) {
 /**
  * DocLocation
  * @constructor
- * @param {Number} line
- * @param {Number} column
+ * @param {number} line
+ * @param {number} column
  * @param {(Object|DocLocation)} [rel]
  */
 function DocLocation(line, column, rel) {
@@ -173,9 +174,9 @@ function DocLocation(line, column, rel) {
 
 /**
  * Shift location by line and column
- * @param {Number|Object} line
- * @param {Number} [column]
- * @return {DocLocation}
+ * @param {number|Object} line
+ * @param {number} [column]
+ * @returns {DocLocation}
  */
 DocLocation.prototype.shift = function(line, column) {
     if (typeof line === 'object') {
@@ -187,7 +188,7 @@ DocLocation.prototype.shift = function(line, column) {
 
 /**
  * Comment parsing helper
- * @param {String} comment
+ * @param {string} comment
  * @returns {Object}
  * @private
  */
@@ -232,7 +233,7 @@ function _parseComment(comment) {
 /**
  * Additional name parsing logic for our purposes
  * @param {string} str - unparsed name thing
- * @return {Object}
+ * @returns {Object}
  */
 function _parseNameAgain(str) { // (?:\s+(\S+))?
     var out = {};
@@ -296,8 +297,8 @@ function _parseNameAgain(str) { // (?:\s+(\S+))?
 }
 
 /**
- * @param {String} typeString
- * @return {?Array.<SimplifiedType>} - parsed jsdoctype string as array
+ * @param {string} typeString
+ * @returns {?Array.<SimplifiedType>} - parsed jsdoctype string as array
  */
 function _parseDocType(typeString) {
     var parser = new TypeParser();
@@ -313,6 +314,11 @@ function _parseDocType(typeString) {
     return node;
 }
 
+/**
+ * @param {EsprimaNode} node
+ * @param {Function} cb
+ * @returns {Array}
+ */
 function _iterateDocTypes(node, cb) {
     var res;
 
@@ -413,7 +419,7 @@ function _iterateDocTypes(node, cb) {
 /**
  * Converts AST jsDoc node to simple object
  * @param {Object} node
- * @returns {!(SimplifiedType[])}
+ * @returns {!Array.<SimplifiedType>}
  * @link https://github.com/Kuniwak/jsdoctypeparser
  */
 function _simplifyType(node) {
@@ -426,7 +432,7 @@ function _simplifyType(node) {
     return res;
 }
 
-var jsPrimitives = 'String Number Boolean Object Array Date Null Undefined Function Array RegExp'
+var jsPrimitives = 'string number boolean null undefined Object Function Array Date RegExp'
     .toLowerCase().split(' ');
 
 /**

lib/rules/validate-jsdoc.js

@@ -4,11 +4,20 @@ var jsdoc = require('../jsdoc');
 var esprimaHelpers = require('../esprima-helpers');
 var validators = require('./validate-jsdoc/index');
 
+/**
+ * Rule constructor
+ * @this {module:jscs/Rule}
+ * @constructor
+ */
 module.exports = function() {};
 
 module.exports.prototype = {
 
-    // load all rules and init them
+    /**
+     * Load all rules and init them
+     * @param {Object} options
+     * @throws {Error} If options is not an Object
+     */
     configure: function(options) {
         assert(typeof options === 'object', 'jsDoc option requires object value');
 
@@ -53,10 +62,17 @@ module.exports.prototype = {
         }, this);
     },
 
+    /**
+     * @returns {string}
+     */
     getOptionName: function() {
         return 'jsDoc';
     },
 
+    /**
+     * @param {module:jscs/JsFile} file
+     * @param {module:jscs/Errors} errors
+     */
     check: function(file, errors) {
         patchNodesInFile(file);
         this._iterate = file.iterate;
@@ -120,6 +136,12 @@ module.exports.prototype = {
                     });
                 });
 
+                /**
+                 * send error to jscs
+                 * @param {string} text
+                 * @param {number|DocLocation} relLine
+                 * @param {number} [relColumn]
+                 */
                 function addError(text, relLine, relColumn) {
                     var line;
                     var column;
@@ -133,6 +155,12 @@ module.exports.prototype = {
                     errors.add(text, line, column);
                 }
 
+                /**
+                 * Generates function with location fixing logic to send error to jscs
+                 * @param {function(string, number|Object, ?number)} err
+                 * @param {DocTag} tag
+                 * @returns {function(string, number|Object, ?number)}
+                 */
                 function fixErrLocation (err, tag) {
                     return function(text, line, column) {
                         line = line || tag.line;
@@ -147,8 +175,7 @@ module.exports.prototype = {
     },
 
     /**
-     * caching scope search
-     * @todo move to patchNodesInFile
+     * caching scope search. todo: move to patchNodesInFile
      * @param {Object} node
      */
     _getReturnStatementsForNode: function(node) {
@@ -189,6 +216,11 @@ function patchNodesInFile(file) {
         });
     });
 
+    /**
+     * Fetchs jsdoc block for this
+     * @this {module:esprima/Node}
+     * @returns {DocComment}
+     */
     function getJsdoc() {
         if (!this.hasOwnProperty('_jsdoc')) {
             var res = findDocCommentBeforeLine(this.loc.start.line);
@@ -197,6 +229,11 @@ function patchNodesInFile(file) {
         return this._jsdoc;
     }
 
+    /**
+     * Finds DocComment in file before passed line number
+     * @param {number} line
+     * @returns {?module:esprima/Node}
+     */
     function findDocCommentBeforeLine(line) {
         line--; // todo: buggy behaviour, can't jump back over empty lines
         for (var i = 0, l = fileComments.length; i < l; i++) {

lib/rules/validate-jsdoc/check-annotations.js

@@ -11,6 +11,9 @@ module.exports.options = {
 
 var tags;
 
+/**
+ * @param {Object} options
+ */
 validateAnnotations.configure = function(options) {
     var o = options.checkAnnotations;
 

lib/rules/validate-jsdoc/check-param-names.js

@@ -31,7 +31,7 @@ function validateCheckParamNames(node, err) {
         /**
          * tag checker
          * @param {DocType} tag
-         * @param {Number} i index
+         * @param {number} i index
          */
         function(tag, i) {
             // checking validity

lib/rules/validate-jsdoc/check-redundant-params.js

@@ -18,7 +18,7 @@ function validateCheckParamNames(node, err) {
         /**
          * tag checker
          * @param {DocType} tag
-         * @param {Number} i index
+         * @param {number} i index
          */
         function(tag, i) {
             // skip if there is dot in param name (object's inner param)

lib/rules/validate-jsdoc/check-types.js

@@ -67,7 +67,12 @@ function validateTypesInTags(file, errors) {
             return;
         }
 
-        node.iterateByType(Object.keys(allowedTags), function(tag) {
+        node.iterateByType(Object.keys(allowedTags),
+            /**
+             * @param {DocType} tag
+             */
+            function(tag) {
+
             if (!tag.type) {
                 // skip untyped params
                 return;

lib/rules/validate-jsdoc/index.js

@@ -20,6 +20,11 @@ var validatorsByName = module.exports = {
 };
 
 Object.defineProperty(validatorsByName, 'load', {
+    /**
+     * loads and initializes existing and required validators
+     * @param {Object} passedOptions
+     * @returns {Array.<Function>}
+     */
     value: function loadValidators(passedOptions) {
         if (!passedOptions) {
             return [];
@@ -51,6 +56,12 @@ Object.defineProperty(validatorsByName, 'load', {
 });
 
 Object.defineProperty(validatorsByName, 'checkOptions', {
+    /**
+     * Validates passed options
+     * @param {Object} validator
+     * @param {Object} options
+     * @throws {Error} If option is not valid
+     */
     value: function checkOptions(validator, options) {
         Object.keys(validator.options).forEach(function(option) {
             var data = validator.options[option];