- Add rule implements-on-classes to prevent @implements on non-constructor functions; fixes #218

Author: brettz9

.README/README.md

@@ -82,6 +82,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-syntax": 1,
         "jsdoc/check-tag-names": 1,
         "jsdoc/check-types": 1,
+        "jsdoc/implements-on-classes": 1,
         "jsdoc/match-description": 1,
         "jsdoc/newline-after-description": 1,
         "jsdoc/no-undefined-types": 1,
@@ -312,6 +313,7 @@ Finally, the following rule pertains to inline disable directives:
 {"gitdown": "include", "file": "./rules/check-syntax.md"}
 {"gitdown": "include", "file": "./rules/check-tag-names.md"}
 {"gitdown": "include", "file": "./rules/check-types.md"}
+{"gitdown": "include", "file": "./rules/implements-on-classes.md"}
 {"gitdown": "include", "file": "./rules/match-description.md"}
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}

.README/rules/implements-on-classes.md

@@ -0,0 +1,13 @@
+### `implements-on-classes`
+
+Reports an issue with any non-constructor function using `@implements`.
+
+Constructor functions, whether marked with `@class`, `@constructs`, or being
+an ES6 class constructor, will not be flagged.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`implements` (prevented)|
+
+<!-- assertions implementsOnClasses -->

README.md

@@ -30,6 +30,7 @@ JSDoc linting rules for ESLint.
         * [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax)
         * [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names)
         * [`check-types`](#eslint-plugin-jsdoc-rules-check-types)
+        * [`implements-on-classes`](#eslint-plugin-jsdoc-rules-implements-on-classes)
         * [`match-description`](#eslint-plugin-jsdoc-rules-match-description)
         * [`newline-after-description`](#eslint-plugin-jsdoc-rules-newline-after-description)
         * [`no-undefined-types`](#eslint-plugin-jsdoc-rules-no-undefined-types)
@@ -125,6 +126,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-syntax": 1,
         "jsdoc/check-tag-names": 1,
         "jsdoc/check-types": 1,
+        "jsdoc/implements-on-classes": 1,
         "jsdoc/match-description": 1,
         "jsdoc/newline-after-description": 1,
         "jsdoc/no-undefined-types": 1,
@@ -1360,6 +1362,64 @@ function qux(foo) {
 ````
 
 
+<a name="eslint-plugin-jsdoc-rules-implements-on-classes"></a>
+### <code>implements-on-classes</code>
+
+Reports an issue with any non-constructor function using `@implements`.
+
+Constructor functions, whether marked with `@class`, `@constructs`, or being
+an ES6 class constructor, will not be flagged.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`implements` (prevented)|
+
+The following patterns are considered problems:
+
+````js
+/**
+ * @implements {SomeClass}
+ */
+function quux () {
+
+}
+// Message: @implements used on a non-constructor function
+````
+
+The following patterns are not considered problems:
+
+````js
+/**
+ * @implements {SomeClass}
+ * @class
+ */
+function quux () {
+
+}
+
+/**
+ * @implements {SomeClass}
+ * @constructor
+ */
+function quux () {
+
+}
+
+/**
+ *
+ */
+class quux {
+  /**
+   * @implements {SomeClass}
+   */
+  constructor () {
+
+  }
+}
+````
+
+
 <a name="eslint-plugin-jsdoc-rules-match-description"></a>
 ### <code>match-description</code>
 

src/index.js

@@ -6,6 +6,7 @@ import checkParamNames from './rules/checkParamNames';
 import checkSyntax from './rules/checkSyntax';
 import checkTagNames from './rules/checkTagNames';
 import checkTypes from './rules/checkTypes';
+import implementsOnClasses from './rules/implementsOnClasses';
 import matchDescription from './rules/matchDescription';
 import newlineAfterDescription from './rules/newlineAfterDescription';
 import noUndefinedTypes from './rules/noUndefinedTypes';
@@ -35,6 +36,8 @@ export default {
         'jsdoc/check-syntax': 'off',
         'jsdoc/check-tag-names': 'warn',
         'jsdoc/check-types': 'warn',
+        'jsdoc/implements-on-classes': 'warn',
+        'jsdoc/match-description': 'off',
         'jsdoc/newline-after-description': 'warn',
         'jsdoc/no-undefined-types': 'warn',
         'jsdoc/require-description': 'off',
@@ -62,6 +65,7 @@ export default {
     'check-syntax': checkSyntax,
     'check-tag-names': checkTagNames,
     'check-types': checkTypes,
+    'implements-on-classes': implementsOnClasses,
     'match-description': matchDescription,
     'newline-after-description': newlineAfterDescription,
     'no-undefined-types': noUndefinedTypes,

src/rules/implementsOnClasses.js

@@ -0,0 +1,18 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  report,
+  utils
+}) => {
+  if (
+    utils.hasATag([
+      'class',
+      'constructor'
+    ]) ||
+    utils.isConstructor()
+  ) {
+    return;
+  }
+
+  report('@implements used on a non-constructor function');
+});

test/rules/assertions/implementsOnClasses.js

@@ -0,0 +1,58 @@
+export default {
+  invalid: [
+    {
+      code: `
+      /**
+       * @implements {SomeClass}
+       */
+      function quux () {
+
+      }
+      `,
+      errors: [
+        {
+          message: '@implements used on a non-constructor function'
+        }
+      ]
+    }
+  ],
+  valid: [
+    {
+      code: `
+      /**
+       * @implements {SomeClass}
+       * @class
+       */
+      function quux () {
+
+      }
+      `
+    },
+    {
+      code: `
+      /**
+       * @implements {SomeClass}
+       * @constructor
+       */
+      function quux () {
+
+      }
+      `
+    },
+    {
+      code: `
+      /**
+       *
+       */
+      class quux {
+        /**
+         * @implements {SomeClass}
+         */
+        constructor () {
+
+        }
+      }
+      `
+    }
+  ]
+};

test/rules/index.js

@@ -14,6 +14,7 @@ const ruleTester = new RuleTester();
   'check-syntax',
   'check-tag-names',
   'check-types',
+  'implements-on-classes',
   'match-description',
   'newline-after-description',
   'no-undefined-types',