leadingUnderscoreAccess: added exception list, fixed location bug

Ref #68

Author: qfox

README.md

@@ -493,6 +493,8 @@ function _f() {}
 
 Ensures access declaration is set for `_underscored` function names
 
+Ignores a bunch of popular identifiers: `__filename`, `__dirname`, `__proto__`, `__defineGetter__`, `super_`, `__constructor`, etc.
+
 Type: `Boolean` or `String`
 
 Values: `true` (means not public), `"private"`, `"protected"`

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

@@ -7,6 +7,30 @@ module.exports.options = {
     }
 };
 
+var nativeUnderscoredProperties = [
+    // standard
+    '__proto__',
+    // underscore
+    '_',
+    // node.js
+    '__filename',
+    '__dirname',
+    'super_', // util.inherits
+    // moz
+    '__count__',
+    '__parent__',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+    '__noSuchMethod__',
+    // dfilatov/inherit
+    '__constructor',
+    '__self',
+    '__base',
+    '__parent',
+];
+
 /**
  * validator for jsdoc data existance
  * @param {(FunctionDeclaration|FunctionExpression)} node
@@ -20,31 +44,43 @@ function validateLeadingUnderscoresAccess(node, err) {
 
     // 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;
     }
 
+    if (nativeUnderscoredProperties.indexOf(name) !== -1) {
+        return;
+    }
+
     // skip anonymous and names without underscores at begin
     if (!name || name[0] !== '_') {
         return;
     }
 
     var access;
+    var accessTag;
     node.jsdoc.iterate(function(tag) {
         if (!access && ['private', 'protected', 'public', 'access'].indexOf(tag.id) !== -1) {
             access = (tag.id === 'access' ? tag.name.value : tag.id);
+            accessTag = tag;
         }
     });
 
-    if (!access || [true, access].indexOf(option) === -1) {
-        err('Method access doesn\'t match');
+    if (!access || !accessTag) {
+        err('Missing access tag for ' + (name || 'anonymous function'), (nameLocation || node.loc).start);
+    } else if ([true, access].indexOf(option) === -1) {
+        err('Method access doesn\'t match', accessTag.loc);
     }
 }

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

@@ -94,9 +94,9 @@ describe('lib/rules/validate-jsdoc/leading-underscore-access', function () {
                     function _funcName(p) {}
                 },
                 errors: [{
-                    line: 6,
-                    column: 0,
-                    message: 'Method access doesn\'t match',
+                    line: 9,
+                    column: 9,
+                    message: 'Missing access tag for _funcName',
                     rule: 'jsDoc',
                     filename: 'input'
                 }]
@@ -180,7 +180,27 @@ describe('lib/rules/validate-jsdoc/leading-underscore-access', function () {
                      */
                     var _pubFuncWithUnderscore = function (p) {};
                 },
-                errors: 2
+                errors: [{
+                    column: 3, line: 2, filename: 'input', rule: 'jsDoc',
+                    message: 'Method access doesn\'t match'
+                }, {
+                    column: 3, line: 7, filename: 'input', rule: 'jsDoc',
+                    message: 'Method access doesn\'t match'
+                }]
+            }, {
+                it: 'should not report standard idendifiers',
+                rules: {leadingUnderscoreAccess: 'protected'},
+                code: function () {
+                    /**
+                     * @access private
+                     */
+                    var super_ = function (p) {};
+
+                    /**
+                     * @access public
+                     */
+                    var __proto__ = function (p) {};
+                }
             }
             /* jshint ignore:end */
         ]);