checkRedundantAccess: added rule to enforcing dangling underscores

Fixes #70

Author: qfox

README.md

@@ -456,9 +456,9 @@ var x = 1;
 
 Reports redundant access declarations
 
-Type: `Boolean`
+Type: `Boolean` or `String`
 
-Values: `true`
+Values: `true` or `"enforceLeadingUnderscore"` or `"enforceTrailingUnderscore"`
 
 Context: `functions`
 
@@ -468,18 +468,24 @@ Tags: `access`, `private`, `protected`, `public`
 
 ```js
 "checkRedundantAccess": true
+"checkRedundantAccess": "enforceLeadingUnderscore"
 ```
 
-##### Valid
+##### Valid for true, "enforceLeadingUnderscore"
 
 ```js
 /**
  * @access private
  */
 function _f() {}
+
+/**
+ * @access public
+ */
+function f() {}
 ```
 
-##### Invalid
+##### Invalid for true
 
 ```js
 /**
@@ -489,6 +495,15 @@ function _f() {}
 function _f() {}
 ```
 
+##### Invalid for "enforceLeadingUnderscore"
+
+```js
+/**
+ * @private
+ */
+function _f() {}
+```
+
 ### leadingUnderscoreAccess
 
 Ensures access declaration is set for `_underscored` function names
@@ -506,7 +521,7 @@ Tags: `access`, `private`, `protected`, `public`
 #### Example
 
 ```js
-"checkRedundantAccess": "protected"
+"leadingUnderscoreAccess": "protected"
 ```
 
 ##### Valid

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

@@ -2,7 +2,7 @@ module.exports = checkRedundantAccess;
 module.exports.scopes = ['function'];
 
 module.exports.options = {
-    checkRedundantAccess: {allowedValues: [true]}
+    checkRedundantAccess: {allowedValues: [true, 'enforceLeadingUnderscore', 'enforceTrailingUnderscore']}
 };
 
 /**
@@ -11,16 +11,14 @@ module.exports.options = {
  * @param {Function} err
  */
 function checkRedundantAccess(node, err) {
+    var enforceLeadingUnderscore = this._options.checkRedundantAccess === 'enforceLeadingUnderscore';
+    var enforceTrailingUnderscore = this._options.checkRedundantAccess === 'enforceTrailingUnderscore';
     if (!node.jsdoc) {
         return;
     }
 
     var access;
-    node.jsdoc.iterate(function(tag) {
-        if (['private', 'protected', 'public', 'access'].indexOf(tag.id) === -1) {
-            return;
-        }
-
+    node.jsdoc.iterateByType(['private', 'protected', 'public', 'access'], function(tag) {
         if (access) {
             err('Multiple access definition', tag.loc);
             return;
@@ -30,6 +28,32 @@ function checkRedundantAccess(node, err) {
             err('Invalid access definition', tag.loc);
         }
 
-        access = tag.id === 'access' ? tag.name : tag.id || 'unspecified';
+        access = tag.id === 'access' ? tag.name.value : tag.id;
     });
+
+    if (access !== 'public' && (enforceLeadingUnderscore || enforceTrailingUnderscore)) {
+        // fetch name from variable, property or function
+        var name;
+        var nameLocation;
+        switch (node.parentNode.type) {
+        case 'VariableDeclarator':
+            name = node.parentNode.id.name;
+            nameLocation = node.parentNode.id.loc;
+            break;
+        case 'Property':
+            name = node.parentNode.key.name;
+            nameLocation = node.parentNode.key.loc;
+            break;
+        default: // try to use func name itself (if not anonymous)
+            name = (node.id || {}).name;
+            nameLocation = (node.id || {}).loc;
+            break;
+        }
+
+        // skip anonymous and names without underscores at begin
+        if (name && name[enforceLeadingUnderscore ? 0 : (name.length - 1)] !== '_') {
+            err('Missing ' + (enforceLeadingUnderscore ? 'leading' : 'trailing') +
+                ' underscore for ' + name, (nameLocation || node.loc).start);
+        }
+    }
 }

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

@@ -72,4 +72,86 @@ describe('lib/rules/validate-jsdoc/check-redundant-access', function () {
 
     });
 
+    describe('with enforceLeadingUnderscore ', function() {
+        checker.rules({checkRedundantAccess: 'enforceLeadingUnderscore'});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report valid jsdoc',
+                code: function () {
+                    /**
+                     * @access protected
+                     */
+                    function _funcName(p) {}
+                },
+                errors: []
+            }, {
+                it: 'should not force publics',
+                code: function () {
+                    /**
+                     * @access public
+                     */
+                    function funcName(p) {}
+                },
+                errors: []
+            }, {
+                it: 'should report missing leading underscore',
+                code: function () {
+                    /**
+                     * @access protected
+                     */
+                    function funcName(p) {}
+                },
+                errors: [{
+                    line: 4, column: 9, filename: 'input', rule: 'jsDoc',
+                    message: 'Missing leading underscore for funcName'
+                }]
+            }
+            /* jshint ignore:end */
+        ]);
+
+    });
+
+    describe('with enforceTrailingUnderscore', function() {
+        checker.rules({checkRedundantAccess: 'enforceTrailingUnderscore'});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report valid jsdoc',
+                code: function () {
+                    /**
+                     * @access protected
+                     */
+                    function funcName_(p) {}
+                },
+                errors: []
+            }, {
+                it: 'should not force publics',
+                code: function () {
+                    /**
+                     * @access public
+                     */
+                    function funcName(p) {}
+                },
+                errors: []
+            }, {
+                it: 'should report missing leading underscore',
+                code: function () {
+                    /**
+                     * @access protected
+                     */
+                    function funcName(p) {}
+                },
+                errors: [{
+                    line: 4, column: 9, filename: 'input', rule: 'jsDoc',
+                    message: 'Missing trailing underscore for funcName'
+                }]
+            }
+            /* jshint ignore:end */
+        ]);
+
+    });
+
 });