Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
enforceExistence: add paramless-procedures exception
Fixes #139
Closes gh-141
  • Loading branch information
Sergey Zarouski authored and Alexej Yaroshevich committed Sep 6, 2015
1 parent c768497 commit 379e9ff
Show file tree
Hide file tree
Showing 4 changed files with 113 additions and 11 deletions.
2 changes: 1 addition & 1 deletion .jscsrc
@@ -1,5 +1,5 @@
{
"plugins": ["jscs-jsdoc"],
"plugins": ["../jscs-jsdoc"],
"preset": "google",

"fileExtensions": [ ".js", ".jscs" ],
Expand Down
13 changes: 10 additions & 3 deletions README.md
Expand Up @@ -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`

Expand Down
36 changes: 29 additions & 7 deletions 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'];
Expand All @@ -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
Expand All @@ -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);
}

};
Expand Down Expand Up @@ -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) {
Expand Down
73 changes: 73 additions & 0 deletions test/lib/rules/validate-jsdoc/enforce-existence.js
Expand Up @@ -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 */
]);
});
});

0 comments on commit 379e9ff

Please sign in to comment.