refactor: switch default mode to typescript; fixes #834

BREAKING CHANGE: Users must now opt into adding `settings.jsdoc.mode` set to `"jsdoc"` if they want normal JSDoc mode. Note that "typescript" mode does not need to imply use of TypeScript syntax, but rather use of the TypeScript flavor within JSDoc comment blocks which holds the advantages of working in IDEs to draw in third-party module documentation and optionally allowing one to type check one's JavaScript code by TypeScript. There are also tools for building docs with this flavor (e.g., typedoc).
gajus · May 7, 2023 · 055adf8 · 055adf8
1 parent 60c8d29
commit 055adf8
Show file tree

Hide file tree

Showing 9 changed files with 30 additions and 4 deletions.
diff --git a/docs/rules/check-tag-names.md b/docs/rules/check-tag-names.md
@@ -720,6 +720,7 @@ function quux (foo) {}
  * @template
  */
 function quux (foo) {}
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
 // Message: Invalid JSDoc tag name "internal".
 
 /** 

diff --git a/docs/rules/check-types.md b/docs/rules/check-types.md
@@ -1179,6 +1179,7 @@ function foo(spec) {
 }
 
 foo()
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
 
 /**
  * @param {object} root

diff --git a/docs/rules/no-undefined-types.md b/docs/rules/no-undefined-types.md
@@ -201,6 +201,7 @@ class Foo {
   bar (baz) {
   }
 }
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
 // Message: The type 'TEMPLATE_TYPE_A' is undefined.
 
 /**

diff --git a/docs/rules/valid-types.md b/docs/rules/valid-types.md
@@ -231,6 +231,7 @@ function quux() {
  * @this
  */
  class Bar {};
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
 // "jsdoc/valid-types": ["error"|"warn", {"allowEmptyNamepaths":false}]
 // Message: Tag @this must have either a type or namepath in "jsdoc" mode.
 

diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -974,10 +974,7 @@ const getSettings = (context) => {
     exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,
 
     // Many rules, e.g., `check-tag-names`
-    mode: context.settings.jsdoc?.mode ??
-      (context.parserPath?.includes('@typescript-eslint') ||
-      context.languageOptions?.parser?.meta?.name?.includes('typescript') ?
-        'typescript' : 'jsdoc'),
+    mode: context.settings.jsdoc?.mode ?? 'typescript',
 
     // Many rules
     contexts: context.settings.jsdoc?.contexts,

diff --git a/test/rules/assertions/checkTagNames.js b/test/rules/assertions/checkTagNames.js
@@ -858,6 +858,11 @@ export default {
           message: 'Invalid JSDoc tag name "template".',
         },
       ],
+      settings: {
+        jsdoc: {
+          mode: 'jsdoc',
+        },
+      },
     },
     {
       code: `${ONE_CLOSURE_TAGS_COMMENT}\nfunction quux (foo) {}`,

diff --git a/test/rules/assertions/checkTypes.js b/test/rules/assertions/checkTypes.js
@@ -3073,6 +3073,11 @@ export default {
 
       foo()
       `,
+      settings: {
+        jsdoc: {
+          mode: 'jsdoc',
+        },
+      },
     },
     {
       code: `

diff --git a/test/rules/assertions/noUndefinedTypes.js b/test/rules/assertions/noUndefinedTypes.js
@@ -276,6 +276,11 @@ export default {
           message: 'The type \'TEMPLATE_TYPE_B\' is undefined.',
         },
       ],
+      settings: {
+        jsdoc: {
+          mode: 'jsdoc',
+        },
+      },
     },
     {
       code: `

diff --git a/test/rules/assertions/validTypes.js b/test/rules/assertions/validTypes.js
@@ -251,6 +251,11 @@ export default {
           allowEmptyNamepaths: false,
         },
       ],
+      settings: {
+        jsdoc: {
+          mode: 'jsdoc',
+        },
+      },
     },
     {
       code: `
@@ -887,6 +892,11 @@ export default {
         },
       ],
       ignoreReadme: true,
+      settings: {
+        jsdoc: {
+          mode: 'jsdoc',
+        },
+      },
     },
     {
       code: `