- Enhancement: Rule to prevent types on @param/@returns

- Docs: Clarify how sentence above preceding list continues

Author: brettz9

.README/README.md

@@ -85,6 +85,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/implements-on-classes": 1,
         "jsdoc/match-description": 1,
         "jsdoc/newline-after-description": 1,
+        "jsdoc/no-types": 1,
         "jsdoc/no-undefined-types": 1,
         "jsdoc/require-description": 1,
         "jsdoc/require-description-complete-sentence": 1,
@@ -316,6 +317,7 @@ Finally, the following rule pertains to inline disable directives:
 {"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-types.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
 {"gitdown": "include", "file": "./rules/require-description.md"}

.README/rules/no-types.md

@@ -0,0 +1,14 @@
+### `no-types`
+
+This rule reports types being used on `@param` or `@returns`.
+
+The rule is intended to prevent the indication of types on tags where
+the type information would be redundant with TypeScript.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`param`, `returns`|
+|Aliases|`arg`, `argument`, `return`|
+
+<!-- assertions noTypes -->

.README/rules/valid-types.md

@@ -10,7 +10,7 @@ Also impacts behaviors on namepath (or event)-defining and pointing tags:
 1. Name(path)-pointing tags (which may have value without namepath): `@listens`, `@fires`, `@emits`
 1. Name(path)-pointing tags (multiple names in one): `@borrows`
 
-The following apply to the above sets:
+...with the following applying to the above sets:
 
 - Expect tags in set 1-4 to have a valid namepath if present
 - Prevent sets 3-4 from being empty by setting `allowEmptyNamepaths` to `false` as these tags might have some indicative value without a path (but sets 1-2 will always fail if empty)

src/index.js

@@ -9,6 +9,7 @@ import checkTypes from './rules/checkTypes';
 import implementsOnClasses from './rules/implementsOnClasses';
 import matchDescription from './rules/matchDescription';
 import newlineAfterDescription from './rules/newlineAfterDescription';
+import noTypes from './rules/noTypes';
 import noUndefinedTypes from './rules/noUndefinedTypes';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence';
 import requireDescription from './rules/requireDescription';
@@ -39,6 +40,7 @@ export default {
         'jsdoc/implements-on-classes': 'warn',
         'jsdoc/match-description': 'off',
         'jsdoc/newline-after-description': 'warn',
+        'jsdoc/no-types': 'off',
         'jsdoc/no-undefined-types': 'warn',
         'jsdoc/require-description': 'off',
         'jsdoc/require-description-complete-sentence': 'off',
@@ -68,6 +70,7 @@ export default {
     'implements-on-classes': implementsOnClasses,
     'match-description': matchDescription,
     'newline-after-description': newlineAfterDescription,
+    'no-types': noTypes,
     'no-undefined-types': noUndefinedTypes,
     'require-description': requireDescription,
     'require-description-complete-sentence': requireDescriptionCompleteSentence,

src/rules/noTypes.js

@@ -0,0 +1,15 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  jsdoc,
+  report
+}) => {
+  const tags = jsdoc.tags.filter((tag) => {
+    return ['param', 'arg', 'argument', 'returns', 'return'].includes(tag.tag);
+  });
+  tags.forEach((tag) => {
+    if (tag.type) {
+      report(`Types are not permitted on @${tag.tag}.`, null, tag);
+    }
+  });
+});

test/rules/assertions/noTypes.js

@@ -0,0 +1,46 @@
+export default {
+  invalid: [
+    {
+      code: `
+          /**
+           * @param {number} foo
+           */
+          function quux (foo) {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Types are not permitted on @param.'
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           * @returns {number}
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Types are not permitted on @returns.'
+        }
+      ]
+    }
+  ],
+  valid: [
+    {
+      code: `
+          /**
+           * @param foo
+           */
+          function quux (foo) {
+
+          }
+      `
+    }
+  ]
+};

test/rules/index.js

@@ -17,6 +17,7 @@ const ruleTester = new RuleTester();
   'implements-on-classes',
   'match-description',
   'newline-after-description',
+  'no-types',
   'no-undefined-types',
   'require-description',
   'require-description-complete-sentence',