enforceExistence: add paramless-procedures exception

Fixes #139
Closes gh-141

Author: Sergey Zarouski

.jscsrc

@@ -1,5 +1,5 @@
 {
-    "plugins": ["jscs-jsdoc"],
+    "plugins": ["../jscs-jsdoc"],
     "preset": "google",
 
     "fileExtensions": [ ".js", ".jscs" ],

README.md

@@ -552,9 +552,16 @@ function _e() {}
 
 Ensures jsdoc block exist
 
-Type: `Boolean` or `String`
-
-Values: `true` or `"exceptExports"` (skip `module.exports = function () {};`)
+Type: `Boolean`, `String` or `Object`
+
+Values:
+- `true`
+- `"exceptExports"` (*deprecated* use `"allExcept": ["exports"]`)
+- `Object`:
+  - `"allExcept"` array of exceptions:
+    - `"expressions"` skip expression functions
+    - `"exports"` skip `module.exports = function () {};`
+    - `"paramless-procedures"` functions without parameters and with empty return statements will be skipped
 
 Context: `functions`
 

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

@@ -1,4 +1,5 @@
 var assert = require('assert');
+var esprimaHelpers = require('../../esprima-helpers');
 
 module.exports = enforceExistence;
 module.exports.scopes = ['function'];
@@ -16,7 +17,8 @@ enforceExistence.configure = function(options) {
         all: true,
         anonymous: false,
         exports: true,
-        expressions: true
+        expressions: true,
+        'paramless-procedures': true,
     };
 
     // check options are valid
@@ -26,18 +28,23 @@ enforceExistence.configure = function(options) {
         'jsDoc.enforceExistence rule was not configured properly'
     );
 
+    var optionsToPolicyMap = Object.keys(policy);
+    /**
+     * @param {string} option
+     */
+    function updatePolicyRules(option) {
+        if (o.allExcept.indexOf(option) > -1) {
+            policy[option] = !policy[option];
+        }
+    }
+
     // 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;
-        }
+        optionsToPolicyMap.forEach(updatePolicyRules);
     }
 
 };
@@ -80,6 +87,21 @@ function enforceExistence(node, err) {
             return;
         }
     }
+    if (policy['paramless-procedures'] === false) {
+        var hasReturnsWhichRequireJsdoc = false;
+        this._iterate(function(n) {
+            if (hasReturnsWhichRequireJsdoc) {
+                return;
+            }
+            var isReturnWithValue = n && n.type === 'ReturnStatement' && n.argument;
+            var isInCurrentScope = node === esprimaHelpers.closestScopeNode(n);
+            hasReturnsWhichRequireJsdoc = isReturnWithValue && isInCurrentScope;
+        }, node);
+        if (!node.params.length && !hasReturnsWhichRequireJsdoc) {
+            // don't check functions without params
+            return;
+        }
+    }
 
     // now clear to check for documentation
     if (node.jsdoc) {

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

@@ -218,4 +218,77 @@ describe('lib/rules/validate-jsdoc/enforce-existence', function () {
         ]);
     });
 
+	describe('with allExcept paramless-procedures', function() {
+		checker.rules({enforceExistence: {allExcept: ['paramless-procedures']}});
+
+		checker.cases([
+			/* jshint ignore:start */
+			{
+				it: 'should not report jsdocs absence for function expressions without parameters',
+				code: function () {
+					var functionalExpression = function () {
+					};
+				}
+			}, {
+				it: 'should not report jsdocs absence for function declarations without parameters',
+				code: function () {
+					function func() {
+					}
+				}
+			}, {
+				it: 'should not report jsdocs absence for function expressions with undefined returns',
+				code: function () {
+					var functionalExpression = function () {
+						return;
+					};
+					var functionalExpressionNoReturn = function () {
+                        /** @returns {number}*/
+                        var nestedHasReturn = function () {
+                            return 1;
+                        };
+					};
+				}
+			}, {
+				it: 'should report jsdocs absence for function expressions with defined returns',
+				code: function () {
+					var functionalExpression = function () {
+						return false;
+					};
+                    var functionalExpressionNoReturn = function () {
+                        var nestedHasReturn = function () {
+                            return 1;
+                        };
+                    };
+				},
+				errors: 2
+			}, {
+				it: 'should not report jsdocs absence for function declarations with undefined returns',
+				code: function () {
+					function func() {
+						return;
+					}
+					function noReturn() {
+						/** @returns {number}*/
+						function nestedHasReturn() {
+							return 1;
+						}
+					}
+				}
+			}, {
+				it: 'should report jsdocs absence for function declarations with defined returns',
+				code: function () {
+					function func() {
+						return false;
+					}
+                    function noReturn() {
+                        function nestedHasReturn() {
+                            return 1;
+                        }
+                    }
+				},
+				errors: 2
+			}
+			/* jshint ignore:end */
+		]);
+	});
 });