fix(no-types, require-example, implements-on-classes): allow any to match function variable declarations

docs/rules/no-types.md

@@ -149,6 +149,24 @@ class Example {
  x: number;
 }
 // Message: Types are not permitted on @property in the supplied context.
+
+/**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ */
+const sleep = (ms: number): Promise<unknown> => {};
+// "jsdoc/no-types": ["error"|"warn", {"contexts":["any"]}]
+// Message: Types are not permitted on @param.
+
+/**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ */
+export const sleep = (ms: number): Promise<unknown> => {};
+// "jsdoc/no-types": ["error"|"warn", {"contexts":["any"]}]
+// Message: Types are not permitted on @param.
 ````
 
 

docs/rules/require-example.md

@@ -234,6 +234,15 @@ function quux (someParam) {
 }
 // "jsdoc/require-example": ["error"|"warn", {"enableFixer":false}]
 // Message: Missing JSDoc @example declaration.
+
+/**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ */
+const sleep = (ms: number): Promise<unknown> => {};
+// "jsdoc/require-example": ["error"|"warn", {"contexts":["any"]}]
+// Message: Missing JSDoc @example declaration.
 ````
 
 

src/iterateJsdoc.js

@@ -476,6 +476,7 @@
 /**
  * @typedef {BasicUtils & {
  * isIteratingFunction: IsIteratingFunction,
+ * isIteratingFunctionOrVariable: IsIteratingFunction,
  * isVirtualFunction: IsVirtualFunction,
  * stringify: Stringify,
  * reportJSDoc: ReportJSDoc,
@@ -542,7 +543,7 @@
  seedTokens,
 } = util;
 
 // todo: Change these `any` types once importing types properly.
 
 /**
  * Should use ESLint rule's typing.
@@ -716,14 +717,36 @@
  tagNamePreference,
  } = settings;
 
+ const functionTypes = [
+ 'ArrowFunctionExpression',
+ 'FunctionDeclaration',
+ 'FunctionExpression',
+ 'MethodDefinition',
+ ];
+
  /** @type {IsIteratingFunction} */
  utils.isIteratingFunction = () => {
- return !iteratingAll || [
- 'ArrowFunctionExpression',
- 'FunctionDeclaration',
- 'FunctionExpression',
- 'MethodDefinition',
- ].includes(String(node && node.type));
+ return !iteratingAll || functionTypes.includes(String(node?.type));
+ };
+
+ /** @type {IsIteratingFunction} */
+ utils.isIteratingFunctionOrVariable = () => {
+ if (utils.isIteratingFunction()) {
+ return true;
+ }
+
+ /** @type {import('estree').VariableDeclarator[]} */
+ const declarations = node?.type === 'VariableDeclaration' ?
+ node.declarations :
+ (node?.type === 'ExportNamedDeclaration' && node.declaration?.type === 'VariableDeclaration' ?
+ node.declaration.declarations :
+ []);
+
+ return declarations.some(({
+ init,
+ }) => {
+ return functionTypes.includes(String(init?.type));
+ });
  };
 
  /** @type {IsVirtualFunction} */
@@ -1069,7 +1092,7 @@
  src.number = firstNumber + /** @type {Integer} */ (lastIndex) + idx;
  }
 
  // Todo: Once rewiring of tags may be fixed in comment-parser to reflect
  // missing tags, this step should be added here (so that, e.g.,
  // if accessing `jsdoc.tags`, such as to add a new tag, the
  // correct information will be available)

src/rules/implementsOnClasses.js

@@ -4,7 +4,7 @@ export default iterateJsdoc(({
  report,
  utils,
 }) => {
- const iteratingFunction = utils.isIteratingFunction();
+ const iteratingFunction = utils.isIteratingFunctionOrVariable();
 
  if (iteratingFunction) {
  if (utils.hasATag([

src/rules/noTypes.js

@@ -14,7 +14,7 @@ export default iterateJsdoc(({
  node,
  utils,
 }) => {
- if (!utils.isIteratingFunction() && !utils.isVirtualFunction()) {
+ if (!utils.isIteratingFunctionOrVariable() && !utils.isVirtualFunction()) {
  return;
  }
 

src/rules/requireExample.js

@@ -24,7 +24,7 @@ export default iterateJsdoc(({
  });
 
  if (!functionExamples.length) {
- if (exemptNoArguments && utils.isIteratingFunction() &&
+ if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&
  !utils.hasParams()
  ) {
  return;

test/rules/assertions/noTypes.js

@@ -286,6 +286,74 @@ export default /** @type {import('../index.js').TestCases} */ ({
  }
  `,
  },
+ {
+ code: `
+ /**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ */
+ const sleep = (ms: number): Promise<unknown> => {};
+ `,
+ errors: [
+ {
+ line: 5,
+ message: 'Types are not permitted on @param.',
+ },
+ ],
+ languageOptions: {
+ parser: typescriptEslintParser,
+ },
+ options: [
+ {
+ contexts: [
+ 'any',
+ ],
+ },
+ ],
+ output: `
+ /**
+ * Returns a Promise...
+ *
+ * @param ms - The number of ...
+ */
+ const sleep = (ms: number): Promise<unknown> => {};
+ `,
+ },
+ {
+ code: `
+ /**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ */
+ export const sleep = (ms: number): Promise<unknown> => {};
+ `,
+ errors: [
+ {
+ line: 5,
+ message: 'Types are not permitted on @param.',
+ },
+ ],
+ languageOptions: {
+ parser: typescriptEslintParser,
+ },
+ options: [
+ {
+ contexts: [
+ 'any',
+ ],
+ },
+ ],
+ output: `
+ /**
+ * Returns a Promise...
+ *
+ * @param ms - The number of ...
+ */
+ export const sleep = (ms: number): Promise<unknown> => {};
+ `,
+ },
  ],
  valid: [
  {

test/rules/assertions/requireExample.js

@@ -1,3 +1,7 @@
+import {
+ parser as typescriptEslintParser,
+} from 'typescript-eslint';
+
 export default /** @type {import('../index.js').TestCases} */ ({
  invalid: [
  {
@@ -378,6 +382,41 @@ function quux () {
  ],
  output: null,
  },
+ {
+ code: `
+ /**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ */
+ const sleep = (ms: number): Promise<unknown> => {};
+ `,
+ errors: [
+ {
+ line: 2,
+ message: 'Missing JSDoc @example declaration.',
+ },
+ ],
+ languageOptions: {
+ parser: typescriptEslintParser,
+ },
+ options: [
+ {
+ contexts: [
+ 'any',
+ ],
+ },
+ ],
+ output: `
+ /**
+ * Returns a Promise...
+ *
+ * @param {number} ms - The number of ...
+ * @example
+ */
+ const sleep = (ms: number): Promise<unknown> => {};
+ `,
+ },
  ],
  valid: [
  {