- Expand loosening brought by param checking with `is(*)AllowedWithou…

…tParam` options to include methods whose class has the tag instead (i.e., @OverRide, @implements, @Augments, or @extends) - Testing (Update): Deprecated Mocha --compilers flag; see https://github.com/mochajs/mocha/wiki/compilers-deprecation
gajus · Nov 13, 2018 · 4ab685b · 4ab685b
1 parent 7898aee
commit 4ab685b
Show file tree

Hide file tree

Showing 5 changed files with 490 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -1350,6 +1350,82 @@ function quux (foo) {
 
 }
 // Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @implements
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @augments
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @extends
+ */
+function quux (foo) {
+
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @override
+ */
+class A {
+  /**
+    *
+    */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @implements
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @augments
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
+
+/**
+ * @extends
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Message: Missing JSDoc @param "foo" declaration.
 ```
 
 The following patterns are not considered problems:
@@ -1392,6 +1468,154 @@ function quux (foo) {
 
 }
 // Settings: {"jsdoc":{"allowOverrideWithoutParam":true}}
+
+/**
+ * @implements
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}}
+
+/**
+ * @implements
+ * @param foo
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @augments
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
+
+/**
+ * @augments
+ * @param foo
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @extends
+ */
+function quux (foo) {
+
+}
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
+
+/**
+ * @extends
+ * @param foo
+ */
+function quux (foo) {
+
+}
+
+/**
+ * @override
+ */
+class A {
+  /**
+  * @param foo
+  */
+  quux (foo) {
+
+  }
+}
+
+/**
+ * @override
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"allowOverrideWithoutParam":true}}
+
+/**
+ * @implements
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"allowImplementsWithoutParam":true}}
+
+/**
+ * @implements
+ */
+class A {
+  /**
+   * @param foo
+   */
+  quux (foo) {
+
+  }
+}
+
+/**
+ * @augments
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
+
+/**
+ * @augments
+ */
+class A {
+  /**
+   * @param foo
+   */
+  quux (foo) {
+
+  }
+}
+
+/**
+ * @extends
+ */
+class A {
+  /**
+   *
+   */
+  quux (foo) {
+
+  }
+}
+// Settings: {"jsdoc":{"allowAugmentsExtendsWithoutParam":true}}
+
+/**
+ * @extends
+ */
+class A {
+  /**
+   * @param foo
+   */
+  quux (foo) {
+
+  }
+}
 ```
 
 

diff --git a/package.json b/package.json
@@ -63,7 +63,7 @@
     "build": "rm -fr ./dist && NODE_ENV=production babel ./src --out-dir ./dist --copy-files --source-maps",
     "create-readme": "gitdown ./.README/README.md --output-file ./README.md && npm run add-assertions",
     "lint": "eslint ./src ./test",
-    "test": "mocha --recursive --compilers js:@babel/register"
+    "test": "mocha --recursive --require @babel/register"
   },
   "version": "2.4.0"
 }
diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -2,10 +2,29 @@ import _ from 'lodash';
 import commentParser from 'comment-parser';
 import jsdocUtils from './jsdocUtils';
 
+const parseComment = (commentNode, indent) => {
+  // Preserve JSDoc block start/end indentation.
+  return commentParser(indent + '/*' + commentNode.value + indent + '*/', {
+    // @see https://github.com/yavorskiy/comment-parser/issues/21
+    parsers: [
+      commentParser.PARSERS.parse_tag,
+      commentParser.PARSERS.parse_type,
+      (str, data) => {
+        if (_.includes(['return', 'returns'], data.tag)) {
+          return null;
+        }
+
+        return commentParser.PARSERS.parse_name(str, data);
+      },
+      commentParser.PARSERS.parse_description
+    ]
+  })[0] || {};
+};
+
 const curryUtils = (
   functionNode, jsdoc, tagNamePreference, additionalTagNames,
   allowOverrideWithoutParam, allowImplementsWithoutParam,
-  allowAugmentsExtendsWithoutParam
+  allowAugmentsExtendsWithoutParam, ancestors, sourceCode
 ) => {
   const utils = {};
 
@@ -45,28 +64,28 @@ const curryUtils = (
     return allowAugmentsExtendsWithoutParam;
   };
 
-  return utils;
-};
+  utils.classHasTag = function (tagName) {
+    const greatGrandParent = ancestors.slice(-3)[0];
+    const greatGrandParentValue = greatGrandParent && sourceCode.getFirstToken(greatGrandParent).value;
 
-export const parseComment = (commentNode, indent) => {
-  // Preserve JSDoc block start/end indentation.
-  return commentParser(indent + '/*' + commentNode.value + indent + '*/', {
-    // @see https://github.com/yavorskiy/comment-parser/issues/21
-    parsers: [
-      commentParser.PARSERS.parse_tag,
-      commentParser.PARSERS.parse_type,
-      (str, data) => {
-        if (_.includes(['return', 'returns'], data.tag)) {
-          return null;
-        }
+    if (greatGrandParentValue === 'class') {
+      const classJsdocNode = sourceCode.getJSDocComment(greatGrandParent);
+      const indent = _.repeat(' ', classJsdocNode.loc.start.column);
+      const classJsdoc = parseComment(classJsdocNode, indent);
 
-        return commentParser.PARSERS.parse_name(str, data);
-      },
-      commentParser.PARSERS.parse_description
-    ]
-  })[0] || {};
+      if (jsdocUtils.hasTag(classJsdoc, tagName)) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
+  return utils;
 };
 
+export {parseComment};
+
 export default (iterator) => {
   return (context) => {
     const sourceCode = context.getSourceCode();
@@ -82,6 +101,7 @@ export default (iterator) => {
       if (!jsdocNode) {
         return;
       }
+      const ancestors = context.getAncestors();
 
       const indent = _.repeat(' ', jsdocNode.loc.start.column);
 
@@ -117,7 +137,7 @@ export default (iterator) => {
       const utils = curryUtils(
         functionNode, jsdoc, tagNamePreference, additionalTagNames,
         allowOverrideWithoutParam, allowImplementsWithoutParam,
-        allowAugmentsExtendsWithoutParam
+        allowAugmentsExtendsWithoutParam, ancestors, sourceCode
       );
 
       iterator({

diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
@@ -1,7 +1,7 @@
 import _ from 'lodash';
 import iterateJsdoc from '../iterateJsdoc';
 
-export default iterateJsdoc(({
+export default iterateJsdoc(({ // eslint-disable-line complexity
   report,
   utils
 }) => {
@@ -15,19 +15,20 @@ export default iterateJsdoc(({
 
   // When settings.jsdoc.allowOverrideWithoutParam is true, override implies that all documentation is inherited.
   // See https://github.com/gajus/eslint-plugin-jsdoc/issues/73
-  if (utils.hasTag('override') && utils.isOverrideAllowedWithoutParam()) {
+  if ((utils.hasTag('override') || utils.classHasTag('override')) && utils.isOverrideAllowedWithoutParam()) {
     return;
   }
 
   // When settings.jsdoc.allowImplementsWithoutParam is true, implements implies that all documentation is inherited.
   // See https://github.com/gajus/eslint-plugin-jsdoc/issues/100
-  if (utils.hasTag('implements') && utils.isImplementsAllowedWithoutParam()) {
+  if ((utils.hasTag('implements') || utils.classHasTag('implements')) && utils.isImplementsAllowedWithoutParam()) {
     return;
   }
 
   // When settings.jsdoc.allowAugmentsExtendsWithoutParam is true, augments or extends implies that all documentation is inherited.
   // See https://github.com/gajus/eslint-plugin-jsdoc/issues/100
-  if ((utils.hasTag('augments') || utils.hasTag('extends')) && utils.isAugmentsExtendsAllowedWithoutParam()) {
+  if ((utils.hasTag('augments') || utils.hasTag('extends') ||
+    utils.classHasTag('augments') || utils.classHasTag('extends')) && utils.isAugmentsExtendsAllowedWithoutParam()) {
     return;
   }