enforceExistence: rework rule, add options to suppress exporting, expressions, etc.

- Refactored configuration and added options to suppress module.export and expression function definitions
- Added further tests and reconfigured configuration parsing

Fixes #110
Closes gh-126

Author: mattvot

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

@@ -1,38 +1,95 @@
+var assert = require('assert');
+
 module.exports = enforceExistence;
 module.exports.scopes = ['function'];
 module.exports.options = {
-    enforceExistence: {allowedValues: [true, 'exceptExports']}
+    enforceExistence: true
 };
 
 /**
- * Validator for jsdoc data existance
+ * @param {Object} options
+ */
+enforceExistence.configure = function(options) {
+
+    // set default policy
+    var policy = this._enforceExistencePolicy = {
+        all: true,
+        anonymous: false,
+        exports: true,
+        expressions: true
+    };
+
+    // check options are valid
+    var o = options.enforceExistence;
+    assert(
+        o === true || o === false || typeof o === 'string' || (typeof o === 'object' && Array.isArray(o.allExcept)),
+        'jsDoc.enforceExistence rule was not configured properly'
+    );
+
+    // parse options for policies
+    if (o === false) {
+        policy.all = false;
+    } else if (typeof o === 'string' && o === 'exceptExports') { // backward compatible string option
+        policy.exports = false;
+    } else if (typeof o === 'object' && Array.isArray(o.allExcept)) {
+        if (o.allExcept.indexOf('exports') > -1) {
+            policy.exports = false;
+        }
+        if (o.allExcept.indexOf('expressions') > -1) {
+            policy.expressions = false;
+        }
+    }
+
+};
+
+/**
+ * Validator for jsdoc data existence
  *
  * @param {(FunctionDeclaration|FunctionExpression)} node
  * @param {Function} err
  */
 function enforceExistence(node, err) {
-    var reportExports = this._options.enforceExistence !== 'exceptExports';
+    var policy = this._enforceExistencePolicy;
 
-    // if function is not anonymous or in variabledeclarator or in assignmentexpression
+    // enforce 'break-out' policies
     var parentNode = node.parentNode || {};
-    var needCheck = node.id ||
-        parentNode.type === 'VariableDeclarator' ||
-        parentNode.type === 'Property' ||
-        parentNode.type === 'AssignmentExpression' && parentNode.operator === '=';
-
-    if (!reportExports && needCheck && parentNode.type === 'AssignmentExpression') {
-        var left = parentNode.left;
-        if ((left.object && left.object.name) === 'module' &&
-            (left.property && left.property.name) === 'exports') {
-            needCheck = false;
+
+    if (policy.all === false) {
+        // don't check anything
+        return;
+    }
+    if (policy.anonymous === false) {
+        if (!node.id && ['AssignmentExpression', 'VariableDeclarator', 'Property'].indexOf(parentNode.type) === -1) {
+            // don't check anonymous functions
+            return;
+        }
+    }
+    if (policy.exports === false) {
+        if (parentNode.type === 'AssignmentExpression') {
+            var left = parentNode.left;
+            if ((left.object && left.object.name) === 'module' &&
+                (left.property && left.property.name) === 'exports') {
+                // don't check exports functions
+                return;
+            }
+        }
+    }
+    if (policy.expressions === false) {
+        if (['AssignmentExpression', 'VariableDeclarator', 'Property'].indexOf(parentNode.type) > -1) {
+            // don't check expression functions
+            return;
         }
     }
 
-    // skip unless jsdoc exists and check is needed
-    if (node.jsdoc || !needCheck) {
+    // now clear to check for documentation
+    if (node.jsdoc) {
+        if (!node.jsdoc.valid) {
+            err('Invalid jsdoc-block definition', node.jsdoc.loc);
+        }
         return;
     }
 
     // report absence
-    err('jsdoc definition required', node.loc.start);
+    err('Expect valid jsdoc-block definition', node.loc.start);
+
 }

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

@@ -8,17 +8,33 @@ describe('lib/rules/validate-jsdoc/enforce-existence', function () {
         it('should report with undefined', function() {
             global.expect(function() {
                 checker.configure({enforceExistence: undefined});
-            }).to.throws(/accepted value/i);
+            }).to.throws(/jsDoc.enforceExistence rule was not configured properly/i);
         });
 
         it('should report with an object', function() {
             global.expect(function() {
-                checker.configure({enforceExistence: {}});
-            }).to.throws(/accepted value/i);
+                checker.configure({enforceExistence: {allExcept: 'something invalid'}});
+            }).to.throws(/jsDoc.enforceExistence rule was not configured properly/i);
         });
 
     });
 
+    describe('with false', function() {
+        checker.rules({enforceExistence: false});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report jsdocs existence for function',
+                code: function () {
+                    function funcName(p) {
+                    }
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+    });
+
     describe('with true', function() {
         checker.rules({enforceExistence: true});
 
@@ -147,4 +163,59 @@ describe('lib/rules/validate-jsdoc/enforce-existence', function () {
         ]);
     });
 
+    describe('with allExcept exports', function() {
+        checker.rules({enforceExistence: {allExcept: ['exports']}});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report jsdocs existence for export functions',
+                errors: 0,
+                code: function () {
+                    module.exports = function () {
+                    };
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+    });
+
+    describe('with allExcept expressions', function() {
+        checker.rules({enforceExistence: {allExcept: ['expressions']}});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report jsdocs existence for expression functions',
+                code: function () {
+                    var x = function () {
+                    };
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+    });
+
+    describe('with allExcept exports and expressions', function() {
+        checker.rules({enforceExistence: {allExcept: ['exports', 'expressions']}});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report jsdocs existence for expression functions',
+                code: function () {
+                    var x = function () {
+                    };
+                }
+            }, {
+                it: 'should not report jsdocs existence for export',
+                code: function () {
+                    module.exports = function () {
+                    };
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+    });
+
 });