some renames, readme update, remove trailingUnderscore, fixes

rename enforce to enforceExistence
rename strict to checkRedundantAccess
moved out strict of leadingUnderscoreAccess checker
upgrade validators interface
fixup incorrects in readme

Author: Alexej Yaroshevich

README.md

@@ -1,9 +1,9 @@
-# jsdoc
+# jscs-jsdoc
 [![Build Status](https://secure.travis-ci.org/zxqfox/jscs-jsdoc.svg?branch=master)](http://travis-ci.org/zxqfox/jscs-jsdoc)
 [![NPM version](https://badge.fury.io/js/jscs-jsdoc.png)](http://badge.fury.io/js/jscs-jsdoc)
 [![Dependency Status](https://david-dm.org/zxqfox/jscs-jsdoc.png)](https://david-dm.org/zxqfox/jscs-jsdoc)
 
-`jscs-jsdoc` plugin for [jscs](https://github.com/mdevils/node-jscs/).
+`jsdoc` plugin for [jscs](https://github.com/mdevils/node-jscs/).
 
 ## Friendly packages
 
@@ -16,7 +16,7 @@ Install it globally if you are using globally installed `jscs`
 
     npm -g install jscs-jsdoc
 
-Or install it into your project
+But better install it into your project
 
     npm install jscs-jsdoc --save-dev
 
@@ -49,12 +49,11 @@ Values:
  - "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
- - "checkTypes" reports invalid types in jsdoc
- - "enforce" reports empty and jsdoc
- - "strict" reports for invalid jsdoc definitions
- - "leadingUnderscoreAccess" reports not set @access for `_underscored` function names
- - "trailingUnderscoreAccess" reports not set @access for `underscored`_ function names
+ - "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
 
@@ -64,12 +63,12 @@ Values:
     "checkRedundantParams": true,
     "requireParamTypes": true,
     "checkReturnTypes": true,
-    "checkRedundantReturns": true,
     "requireReturnTypes": true,
     "checkTypes": true,
-    "strict": true,
-    "enforce": true,
-    "leadingUnderscoreAccess": 'private'
+    "checkRedundantReturns": true,
+    "checkRedundantAccess": true,
+    "leadingUnderscoreAccess": "private",
+    "enforceExistence": true
 }
 ```
 
@@ -103,6 +102,10 @@ _add: function(message, line, column) {
  * @returns {String}
  */
 _add: function() {
+    if (true) {
+        return false;
+    }
+    return 15;
 }
 ```
 
@@ -120,9 +123,9 @@ Download and include `jscs-jsdoc-browser.js` into your page just after `jscs-bro
 <script>
     var checker = new JscsStringChecker();
     checker.registerDefaultRules();
-    checker.configure({'jsDoc': {/*...*/}});
+    checker.configure({'jsDoc': {/* ... */}});
     var errors = checker.checkString('var x, y = 1;');
-    errors.getErrorList().forEach(function(error) {
+    errors.getErrorList().forEach(function (error) {
         console.log(errors.explainError(error));
     });
 </script>

lib/rules/validate-jsdoc.js

@@ -1,27 +1,42 @@
 var assert = require('assert');
 
 var jsDocHelpers = require('../jsdoc-helpers');
-var validatorsByName = require('./validate-jsdoc/index');
+var validators = require('./validate-jsdoc/index');
 
 module.exports = function() {};
 
 module.exports.prototype = {
 
     configure: function (options) {
         assert(typeof options === 'object', 'jsDoc option requires object value');
+
         this._options = options;
         this._optionsList = Object.keys(options);
+        this._validators = validators.load(this._optionsList);
+
+        assert(this._validators.length, 'jsDoc was not configured properly');
+
+        this._validators.forEach(function (v) {
+            if (v.configure) {
+                v.configure.call(this, options);
+            }
+            if (v.options) {
+                validators.checkOptions(v, options);
+            }
+        }.bind(this));
+
+
     },
 
     getOptionName: function () {
         return 'jsDoc';
     },
 
     check: function (file, errors) {
-        var validators = this.loadValidators();
+        var activeValidators = this._validators;
 
-        // skip if there is nothing to check
-        if (!validators.length) {
+        // skip if there is no validators
+        if (!activeValidators.length) {
             return;
         }
 
@@ -34,8 +49,8 @@ module.exports.prototype = {
 
         ], function (node) {
             node.jsDoc = jsDocs.forNode(node);
-            for (var j = 0, k = validators.length; j < k; j += 1) {
-                validators[j].call(that, node, addError);
+            for (var j = 0, k = activeValidators.length; j < k; j += 1) {
+                activeValidators[j].call(that, node, addError);
             }
 
             function addError(text, loc) {
@@ -46,32 +61,5 @@ module.exports.prototype = {
             }
         });
 
-    },
-
-    loadValidators: function () {
-        var passedOptions = this._optionsList;
-        var validators = [];
-        if (!passedOptions) {
-            return validators;
-        }
-
-        Object.keys(validatorsByName).forEach(function (name) {
-            var v = validatorsByName[name];
-
-            // skip unused
-            if (!v.coveredOptions) {
-                return;
-            }
-
-            // store used
-            for (var i = 0, l = v.coveredOptions.length; i < l; i += 1) {
-                if (passedOptions.indexOf(v.coveredOptions[i]) !== -1) {
-                    validators.push(v);
-                    return;
-                }
-            }
-        }.bind(this));
-
-        return validators;
     }
 };

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

@@ -0,0 +1,34 @@
+module.exports = checkRedundantAccess;
+
+module.exports.options = {
+    checkRedundantAccess: {allowedValues: [true]}
+};
+
+/**
+ * validator for @access
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {Function} err
+ */
+function checkRedundantAccess(node, err) {
+    if (!node.jsDoc) {
+        return;
+    }
+
+	var access;
+    node.jsDoc.data.tags.forEach(function (tag) {
+        if (['private', 'protected', 'public', 'access'].indexOf(tag.tag) === -1) {
+            return;
+        }
+
+        if (access) {
+        	err('Multiple access definition');
+        	return;
+        }
+
+        if (tag.tag === 'access' && !tag.name) {
+            err('Invalid access definition');
+        }
+
+        access = tag.tag === 'access' ? tag.name : tag.tag || 'unspecified';
+    });
+}

lib/rules/validate-jsdoc/enforce-existence.js

@@ -0,0 +1,16 @@
+module.exports = enforceExistence;
+
+module.exports.options = {
+    enforceExistence: {allowedValues: [true]}
+};
+
+/**
+ * validator for jsdoc data existance
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {Function} err
+ */
+function enforceExistence(node, err) {
+    if (!node.jsDoc) {
+        err('jsdoc definition required', node.loc.start);
+    }
+}

lib/rules/validate-jsdoc/enforce.js

@@ -1,6 +1,67 @@
-module.exports = {
-    enforce: require('./enforce'),
+var assert = require('assert');
+
+var validatorsByName = module.exports = {
     param: require('./param'),
     returns: require('./returns'),
-    trailingUnderscores: require('./trailing-underscores')
+    checkRedundantAccess: require('./check-redundant-access'),
+    enforceExistence: require('./enforce-existence'),
+    leadingUnderscoreAccess: require('./leading-underscore-access')
 };
+
+Object.defineProperty(validatorsByName, 'load', {
+    value: function loadValidators(passedOptions) {
+        var validators = [];
+
+        if (!passedOptions) {
+            return validators;
+        }
+
+        Object.keys(validatorsByName).forEach(function (name) {
+            var v = validatorsByName[name];
+
+            // skip unknown
+            var coveredOptions = v.coveredOptions || (v.options && Object.keys(v.options));
+            if (!coveredOptions || !coveredOptions.length) {
+                return;
+            }
+
+            // store used
+            for (var i = 0, l = coveredOptions.length; i < l; i += 1) {
+                if (passedOptions.indexOf(coveredOptions[i]) !== -1) {
+                    v._name = name;
+                    validators.push(v);
+                    return;
+                }
+            }
+        });
+
+        return validators;
+    }
+});
+
+Object.defineProperty(validatorsByName, 'checkOptions', {
+    value: function checkOptions(validator, options) {
+        Object.keys(validator.options).forEach(function (data, option) {
+            if (!data.allowedValues) {
+                return;
+            }
+
+            var values;
+            if (typeof data.allowedValues === 'function') {
+                values = data.allowedValues();
+            }
+
+            if (!Array.isArray(values)) {
+                throw new Error('Internal error in jsDoc validator ' + validator._name);
+
+            } else if (values.length > 1) {
+                assert(values.indexOf(options[option]) !== -1,
+                    'Available values for option jsDoc.' + option + ' are ' + values.map(JSON.stringify).join(', '));
+
+            } else if (values.length) {
+                assert(values[0] === options[option],
+                    'Only accepted value for jsDoc.' + option + ' is ' + JSON.stringify(values[0]));
+            }
+        });
+    }
+});

lib/rules/validate-jsdoc/index.js

@@ -0,0 +1,49 @@
+module.exports = validateLeadingUnderscoresAccess;
+
+module.exports.options = {
+    leadingUnderscoreAccess: {
+        allowedValues: [true, 'private', 'protected']
+    }
+};
+
+/**
+ * validator for jsdoc data existance
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {Function} err
+ */
+function validateLeadingUnderscoresAccess(node, err) {
+    var option = this._options.leadingUnderscoreAccess;
+    if (!node.jsDoc) {
+        return;
+    }
+
+    // fetch name from variable, property or function
+    var name;
+    switch (node.parentNode.type) {
+    case 'VariableDeclarator':
+        name = node.parentNode.id.name;
+        break;
+    case 'Property':
+        name = node.parentNode.key.name;
+        break;
+    default: // try to use func name itself (if not anonymous)
+        name = (node.id||{}).name;
+        break;
+    }
+
+    // skip anonymous and names without underscores at begin
+    if (!name || name[0] !== '_') {
+        return;
+    }
+
+    var access;
+    node.jsDoc.data.tags.forEach(function (tag) {
+        if (!access && ['private', 'protected', 'public', 'access'].indexOf(tag.tag) !== -1) {
+            access = (tag.tag === 'access' ? tag.name : tag.tag);
+        }
+    });
+
+    if (!access || [true, access].indexOf(option) === -1) {
+        err('Method access doesn\'t match');
+    }
+}

lib/rules/validate-jsdoc/leading-underscore-access.js

@@ -2,12 +2,21 @@
 var jsDocHelpers = require('../../jsdoc-helpers');
 
 module.exports = jsDocHelpers.tagValidator(validateParamLine);
-module.exports.coveredOptions = [
-    'checkParamNames',
-    'requireParamTypes',
-    'checkRedundantParams',
-    'checkTypes',
-];
+
+module.exports.options = {
+    checkParamNames: {
+        allowedValues: [true]
+    },
+    requireParamTypes: {
+        allowedValues: [true]
+    },
+    checkRedundantParams: {
+        allowedValues: [true]
+    },
+    checkTypes: {
+        allowedValues: [true]
+    }
+};
 
 /**
  * validator for @param