Skip to content

Commit aee2805

Browse files
author
Alexej Yaroshevich
committed
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
1 parent 487eccd commit aee2805

15 files changed

Lines changed: 300 additions & 276 deletions

‎README.md‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# jsdoc
1+
# jscs-jsdoc
22
[![Build Status](https://secure.travis-ci.org/zxqfox/jscs-jsdoc.svg?branch=master)](http://travis-ci.org/zxqfox/jscs-jsdoc)
33
[![NPM version](https://badge.fury.io/js/jscs-jsdoc.png)](http://badge.fury.io/js/jscs-jsdoc)
44
[![Dependency Status](https://david-dm.org/zxqfox/jscs-jsdoc.png)](https://david-dm.org/zxqfox/jscs-jsdoc)
55

6-
`jscs-jsdoc` plugin for [jscs](https://github.com/mdevils/node-jscs/).
6+
`jsdoc` plugin for [jscs](https://github.com/mdevils/node-jscs/).
77

88
## Friendly packages
99

@@ -16,7 +16,7 @@ Install it globally if you are using globally installed `jscs`
1616

1717
npm -g install jscs-jsdoc
1818

19-
Or install it into your project
19+
But better install it into your project
2020

2121
npm install jscs-jsdoc --save-dev
2222

@@ -49,12 +49,11 @@ Values:
4949
- "checkRedundantParams" reports redundant params in jsdoc
5050
- "checkReturnTypes" tries to compare function result type with declared type in jsdoc
5151
- "requireReturnTypes" ensures returns in jsdoc contains type
52+
- "checkTypes" reports invalid types
5253
- "checkRedundantReturns" reports redundant returns in jsdoc
53-
- "checkTypes" reports invalid types in jsdoc
54-
- "enforce" reports empty and jsdoc
55-
- "strict" reports for invalid jsdoc definitions
56-
- "leadingUnderscoreAccess" reports not set @access for `_underscored` function names
57-
- "trailingUnderscoreAccess" reports not set @access for `underscored`_ function names
54+
- "checkRedundantAccess" reports redundant access declarations
55+
- "leadingUnderscoreAccess" ensures access declaration is set for `_underscored` function names
56+
- "enforceExistence" ensures jsdoc declarations exists for functions and methods
5857

5958
#### Example
6059

@@ -64,12 +63,12 @@ Values:
6463
"checkRedundantParams": true,
6564
"requireParamTypes": true,
6665
"checkReturnTypes": true,
67-
"checkRedundantReturns": true,
6866
"requireReturnTypes": true,
6967
"checkTypes": true,
70-
"strict": true,
71-
"enforce": true,
72-
"leadingUnderscoreAccess": 'private'
68+
"checkRedundantReturns": true,
69+
"checkRedundantAccess": true,
70+
"leadingUnderscoreAccess": "private",
71+
"enforceExistence": true
7372
}
7473
```
7574

@@ -103,6 +102,10 @@ _add: function(message, line, column) {
103102
* @returns {String}
104103
*/
105104
_add: function() {
105+
if (true) {
106+
return false;
107+
}
108+
return 15;
106109
}
107110
```
108111

@@ -120,9 +123,9 @@ Download and include `jscs-jsdoc-browser.js` into your page just after `jscs-bro
120123
<script>
121124
var checker = new JscsStringChecker();
122125
checker.registerDefaultRules();
123-
checker.configure({'jsDoc': {/*...*/}});
126+
checker.configure({'jsDoc': {/* ... */}});
124127
var errors = checker.checkString('var x, y = 1;');
125-
errors.getErrorList().forEach(function(error) {
128+
errors.getErrorList().forEach(function (error) {
126129
console.log(errors.explainError(error));
127130
});
128131
</script>

‎lib/rules/validate-jsdoc.js‎

Lines changed: 21 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,42 @@
11
var assert = require('assert');
22

33
var jsDocHelpers = require('../jsdoc-helpers');
4-
var validatorsByName = require('./validate-jsdoc/index');
4+
var validators = require('./validate-jsdoc/index');
55

66
module.exports = function() {};
77

88
module.exports.prototype = {
99

1010
configure: function (options) {
1111
assert(typeof options === 'object', 'jsDoc option requires object value');
12+
1213
this._options = options;
1314
this._optionsList = Object.keys(options);
15+
this._validators = validators.load(this._optionsList);
16+
17+
assert(this._validators.length, 'jsDoc was not configured properly');
18+
19+
this._validators.forEach(function (v) {
20+
if (v.configure) {
21+
v.configure.call(this, options);
22+
}
23+
if (v.options) {
24+
validators.checkOptions(v, options);
25+
}
26+
}.bind(this));
27+
28+
1429
},
1530

1631
getOptionName: function () {
1732
return 'jsDoc';
1833
},
1934

2035
check: function (file, errors) {
21-
var validators = this.loadValidators();
36+
var activeValidators = this._validators;
2237

23-
// skip if there is nothing to check
24-
if (!validators.length) {
38+
// skip if there is no validators
39+
if (!activeValidators.length) {
2540
return;
2641
}
2742

@@ -34,8 +49,8 @@ module.exports.prototype = {
3449

3550
], function (node) {
3651
node.jsDoc = jsDocs.forNode(node);
37-
for (var j = 0, k = validators.length; j < k; j += 1) {
38-
validators[j].call(that, node, addError);
52+
for (var j = 0, k = activeValidators.length; j < k; j += 1) {
53+
activeValidators[j].call(that, node, addError);
3954
}
4055

4156
function addError(text, loc) {
@@ -46,32 +61,5 @@ module.exports.prototype = {
4661
}
4762
});
4863

49-
},
50-
51-
loadValidators: function () {
52-
var passedOptions = this._optionsList;
53-
var validators = [];
54-
if (!passedOptions) {
55-
return validators;
56-
}
57-
58-
Object.keys(validatorsByName).forEach(function (name) {
59-
var v = validatorsByName[name];
60-
61-
// skip unused
62-
if (!v.coveredOptions) {
63-
return;
64-
}
65-
66-
// store used
67-
for (var i = 0, l = v.coveredOptions.length; i < l; i += 1) {
68-
if (passedOptions.indexOf(v.coveredOptions[i]) !== -1) {
69-
validators.push(v);
70-
return;
71-
}
72-
}
73-
}.bind(this));
74-
75-
return validators;
7664
}
7765
};

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
module.exports = checkRedundantAccess;
2+
3+
module.exports.options = {
4+
checkRedundantAccess: {allowedValues: [true]}
5+
};
6+
7+
/**
8+
* validator for @access
9+
* @param {(FunctionDeclaration|FunctionExpression)} node
10+
* @param {Function} err
11+
*/
12+
function checkRedundantAccess(node, err) {
13+
if (!node.jsDoc) {
14+
return;
15+
}
16+
17+
var access;
18+
node.jsDoc.data.tags.forEach(function (tag) {
19+
if (['private', 'protected', 'public', 'access'].indexOf(tag.tag) === -1) {
20+
return;
21+
}
22+
23+
if (access) {
24+
err('Multiple access definition');
25+
return;
26+
}
27+
28+
if (tag.tag === 'access' && !tag.name) {
29+
err('Invalid access definition');
30+
}
31+
32+
access = tag.tag === 'access' ? tag.name : tag.tag || 'unspecified';
33+
});
34+
}

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
module.exports = enforceExistence;
2+
3+
module.exports.options = {
4+
enforceExistence: {allowedValues: [true]}
5+
};
6+
7+
/**
8+
* validator for jsdoc data existance
9+
* @param {(FunctionDeclaration|FunctionExpression)} node
10+
* @param {Function} err
11+
*/
12+
function enforceExistence(node, err) {
13+
if (!node.jsDoc) {
14+
err('jsdoc definition required', node.loc.start);
15+
}
16+
}

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

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎lib/rules/validate-jsdoc/index.js‎

Lines changed: 64 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,67 @@
1-
module.exports = {
2-
enforce: require('./enforce'),
1+
var assert = require('assert');
2+
3+
var validatorsByName = module.exports = {
34
param: require('./param'),
45
returns: require('./returns'),
5-
trailingUnderscores: require('./trailing-underscores')
6+
checkRedundantAccess: require('./check-redundant-access'),
7+
enforceExistence: require('./enforce-existence'),
8+
leadingUnderscoreAccess: require('./leading-underscore-access')
69
};
10+
11+
Object.defineProperty(validatorsByName, 'load', {
12+
value: function loadValidators(passedOptions) {
13+
var validators = [];
14+
15+
if (!passedOptions) {
16+
return validators;
17+
}
18+
19+
Object.keys(validatorsByName).forEach(function (name) {
20+
var v = validatorsByName[name];
21+
22+
// skip unknown
23+
var coveredOptions = v.coveredOptions || (v.options && Object.keys(v.options));
24+
if (!coveredOptions || !coveredOptions.length) {
25+
return;
26+
}
27+
28+
// store used
29+
for (var i = 0, l = coveredOptions.length; i < l; i += 1) {
30+
if (passedOptions.indexOf(coveredOptions[i]) !== -1) {
31+
v._name = name;
32+
validators.push(v);
33+
return;
34+
}
35+
}
36+
});
37+
38+
return validators;
39+
}
40+
});
41+
42+
Object.defineProperty(validatorsByName, 'checkOptions', {
43+
value: function checkOptions(validator, options) {
44+
Object.keys(validator.options).forEach(function (data, option) {
45+
if (!data.allowedValues) {
46+
return;
47+
}
48+
49+
var values;
50+
if (typeof data.allowedValues === 'function') {
51+
values = data.allowedValues();
52+
}
53+
54+
if (!Array.isArray(values)) {
55+
throw new Error('Internal error in jsDoc validator ' + validator._name);
56+
57+
} else if (values.length > 1) {
58+
assert(values.indexOf(options[option]) !== -1,
59+
'Available values for option jsDoc.' + option + ' are ' + values.map(JSON.stringify).join(', '));
60+
61+
} else if (values.length) {
62+
assert(values[0] === options[option],
63+
'Only accepted value for jsDoc.' + option + ' is ' + JSON.stringify(values[0]));
64+
}
65+
});
66+
}
67+
});

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
module.exports = validateLeadingUnderscoresAccess;
2+
3+
module.exports.options = {
4+
leadingUnderscoreAccess: {
5+
allowedValues: [true, 'private', 'protected']
6+
}
7+
};
8+
9+
/**
10+
* validator for jsdoc data existance
11+
* @param {(FunctionDeclaration|FunctionExpression)} node
12+
* @param {Function} err
13+
*/
14+
function validateLeadingUnderscoresAccess(node, err) {
15+
var option = this._options.leadingUnderscoreAccess;
16+
if (!node.jsDoc) {
17+
return;
18+
}
19+
20+
// fetch name from variable, property or function
21+
var name;
22+
switch (node.parentNode.type) {
23+
case 'VariableDeclarator':
24+
name = node.parentNode.id.name;
25+
break;
26+
case 'Property':
27+
name = node.parentNode.key.name;
28+
break;
29+
default: // try to use func name itself (if not anonymous)
30+
name = (node.id||{}).name;
31+
break;
32+
}
33+
34+
// skip anonymous and names without underscores at begin
35+
if (!name || name[0] !== '_') {
36+
return;
37+
}
38+
39+
var access;
40+
node.jsDoc.data.tags.forEach(function (tag) {
41+
if (!access && ['private', 'protected', 'public', 'access'].indexOf(tag.tag) !== -1) {
42+
access = (tag.tag === 'access' ? tag.name : tag.tag);
43+
}
44+
});
45+
46+
if (!access || [true, access].indexOf(option) === -1) {
47+
err('Method access doesn\'t match');
48+
}
49+
}

‎lib/rules/validate-jsdoc/param.js‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,21 @@
22
var jsDocHelpers = require('../../jsdoc-helpers');
33

44
module.exports = jsDocHelpers.tagValidator(validateParamLine);
5-
module.exports.coveredOptions = [
6-
'checkParamNames',
7-
'requireParamTypes',
8-
'checkRedundantParams',
9-
'checkTypes',
10-
];
5+
6+
module.exports.options = {
7+
checkParamNames: {
8+
allowedValues: [true]
9+
},
10+
requireParamTypes: {
11+
allowedValues: [true]
12+
},
13+
checkRedundantParams: {
14+
allowedValues: [true]
15+
},
16+
checkTypes: {
17+
allowedValues: [true]
18+
}
19+
};
1120

1221
/**
1322
* validator for @param

0 commit comments

Comments
 (0)