feat(informative-docs): add excludedTags; fixes #1153

Also: - fix(`informative-docs`): proper `aliases` schema - test(`informative-docs`): check `uselessWords` - test(`require-jsdoc`): example for Vue components
gajus · Sep 10, 2023 · 6f1b50b · 6f1b50b
1 parent 85a21bf
commit 6f1b50b
Show file tree

Hide file tree

Showing 6 changed files with 143 additions and 7 deletions.
diff --git a/.README/rules/informative-docs.md b/.README/rules/informative-docs.md
@@ -60,7 +60,7 @@ The default `uselessWords` option is:
 |Tags|any|
 |Recommended|false|
 |Settings||
-|Options|`aliases`, `uselessWords`|
+|Options|`aliases`, `excludedTags`, `uselessWords`|
 
 ## Failing examples
 

diff --git a/docs/rules/informative-docs.md b/docs/rules/informative-docs.md
@@ -76,7 +76,7 @@ The default `uselessWords` option is:
 |Tags|any|
 |Recommended|false|
 |Settings||
-|Options|`aliases`, `uselessWords`|
+|Options|`aliases`, `excludedTags`, `uselessWords`|
 
 <a name="user-content-informative-docs-failing-examples"></a>
 <a name="informative-docs-failing-examples"></a>
@@ -249,6 +249,11 @@ function takesOne(param) {}
  */
 function takesOne(param) {}
 // Message: This description only repeats the name it describes.
+
+/** A smiley/winkey. */
+let emoji;
+// "jsdoc/informative-docs": ["error"|"warn", {"aliases":{"emoji":["smiley","winkey"]}}]
+// Message: This description only repeats the name it describes.
 ````
 
 
@@ -391,10 +396,21 @@ function takesOne(param) {}
 function takesOne(param) {}
 
 /**
- * @class 
+ * @class
  *
  * @param {number} value - Some useful text
- */      
+ */
 function MyAmazingThing(value) {}
+
+/**
+ * My option.
+ * @default {}
+ */
+// "jsdoc/informative-docs": ["error"|"warn", {"excludedTags":["default"]}]
+
+/**
+ * The
+ */
+// "jsdoc/informative-docs": ["error"|"warn", {"uselessWords":["an"]}]
 ````
 
diff --git a/docs/rules/require-jsdoc.md b/docs/rules/require-jsdoc.md
@@ -1857,5 +1857,27 @@ export default class Test {
   }
 }
 // "jsdoc/require-jsdoc": ["error"|"warn", {"publicOnly":true,"require":{"ArrowFunctionExpression":false,"ClassDeclaration":false,"ClassExpression":false,"FunctionDeclaration":false,"FunctionExpression":false,"MethodDefinition":true}}]
+
+export default {
+  created() {
+    this.getData();
+  },
+
+  beforeUpdate() {},
+
+  watch: {
+    someValue(val) {}
+  },
+
+  computed: {
+    loaded() {},
+    selection() {}
+  },
+
+  methods: {
+    getData(id) {}
+  }
+};
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(created|beforeUpdate)$/] > FunctionExpression","ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(watch|computed|methods)$/] > ObjectExpression > Property > FunctionExpression"]}]
 ````
 
diff --git a/src/rules/informativeDocs.js b/src/rules/informativeDocs.js
@@ -91,8 +91,9 @@ export default iterateJsdoc(({
   report,
   utils,
 }) => {
-  const {
+  const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ {
     aliases = defaultAliases,
+    excludedTags = [],
     uselessWords = defaultUselessWords,
   } = context.options[0] || {};
   const nodeNames = getNamesFromNode(node);
@@ -119,6 +120,10 @@ export default iterateJsdoc(({
   let descriptionReported = false;
 
   for (const tag of jsdoc.tags) {
+    if (excludedTags.includes(tag.tag)) {
+      continue;
+    }
+
     if (descriptionIsRedundant(tag.description, tag.name)) {
       utils.reportJSDoc(
         'This tag description only repeats the name it describes.',
@@ -147,6 +152,16 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           aliases: {
+            patternProperties: {
+              '.*': {
+                items: {
+                  type: 'string',
+                },
+                type: 'array',
+              },
+            },
+          },
+          excludedTags: {
             items: {
               type: 'string',
             },

diff --git a/test/rules/assertions/informativeDocs.js b/test/rules/assertions/informativeDocs.js
@@ -476,6 +476,27 @@ export default {
         },
       ],
     },
+    {
+      code: `
+        /** A smiley/winkey. */
+        let emoji;
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'This description only repeats the name it describes.',
+        },
+      ],
+      options: [
+        {
+          aliases: {
+            emoji: [
+              'smiley', 'winkey',
+            ],
+          },
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -752,12 +773,41 @@ export default {
     {
       code: `
         /**
-         * @class 
+         * @class
          *
          * @param {number} value - Some useful text
-         */      
+         */
         function MyAmazingThing(value) {}
       `,
     },
+    {
+      code: `
+        /**
+         * My option.
+         * @default {}
+         */
+      `,
+      options: [
+        {
+          excludedTags: [
+            'default',
+          ],
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * The
+         */
+      `,
+      options: [
+        {
+          uselessWords: [
+            'an',
+          ],
+        },
+      ],
+    },
   ],
 };
diff --git a/test/rules/assertions/requireJsdoc.js b/test/rules/assertions/requireJsdoc.js
@@ -6202,5 +6202,38 @@ function quux (foo) {
         sourceType: 'module',
       },
     },
+    {
+      code: `
+      export default {
+        created() {
+          this.getData();
+        },
+
+        beforeUpdate() {},
+
+        watch: {
+          someValue(val) {}
+        },
+
+        computed: {
+          loaded() {},
+          selection() {}
+        },
+
+        methods: {
+          getData(id) {}
+        }
+      };
+      `,
+      options: [
+        {
+          contexts: [
+            'ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(created|beforeUpdate)$/] > FunctionExpression',
+            'ExportDefaultDeclaration > ObjectExpression > Property[key.name!=/^(watch|computed|methods)$/] > ObjectExpression > Property > FunctionExpression',
+          ],
+        },
+      ],
+      parser: require.resolve('@typescript-eslint/parser'),
+    },
   ],
 };