eslint-plugin-jsdoc/dist/rules/informativeDocs.cjs.map

JSDoc linting rules for ESLint.

{"version":3,"file":"informativeDocs.cjs","names":["iterateJsdoc","areDocsInformative"],"sources":["../../src/rules/informativeDocs.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n  areDocsInformative,\n} from 'are-docs-informative';\n\nconst defaultAliases = {\n  a: [\n    'an', 'our',\n  ],\n};\n\nconst defaultUselessWords = [\n  'a', 'an', 'i', 'in', 'of', 's', 'the',\n];\n\n/**\n * @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node|null|undefined} node\n * @returns {string[]}\n */\nconst getNamesFromNode = (node) => {\n  switch (node?.type) {\n    case 'AccessorProperty':\n    case 'MethodDefinition':\n    case 'PropertyDefinition':\n    case 'TSAbstractAccessorProperty':\n    case 'TSAbstractMethodDefinition':\n    case 'TSAbstractPropertyDefinition':\n      return [\n        ...getNamesFromNode(\n        /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n            node.parent\n          ).parent,\n        ),\n        ...getNamesFromNode(\n        /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n          (node.key),\n        ),\n      ];\n\n    case 'ClassDeclaration':\n    case 'ClassExpression':\n    case 'FunctionDeclaration':\n    case 'FunctionExpression':\n    case 'TSDeclareFunction':\n    case 'TSEnumDeclaration':\n    case 'TSEnumMember':\n    case 'TSInterfaceDeclaration':\n    case 'TSMethodSignature':\n    case 'TSModuleDeclaration':\n    case 'TSTypeAliasDeclaration':\n      return getNamesFromNode(\n      /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */\n        (node).id,\n      );\n    case 'ExportDefaultDeclaration':\n    case 'ExportNamedDeclaration':\n      return getNamesFromNode(\n      /** @type {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration} */\n        (node).declaration,\n      );\n    case 'Identifier':\n      return [\n        node.name,\n      ];\n    case 'Property':\n      return getNamesFromNode(\n      /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n        (node.key),\n      );\n    case 'VariableDeclaration':\n      return getNamesFromNode(\n      /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n        (node.declarations[0]),\n      );\n    case 'VariableDeclarator':\n      return [\n        ...getNamesFromNode(\n        /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n          (node.id),\n        ),\n        ...getNamesFromNode(\n        /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n          (node.init),\n        ),\n      ].filter(Boolean);\n    default:\n      return [];\n  }\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  node,\n  report,\n  utils,\n}) => {\n  const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ {\n    aliases = defaultAliases,\n    excludedTags = [],\n    uselessWords = defaultUselessWords,\n  } = context.options[0] || {};\n  const nodeNames = getNamesFromNode(node);\n\n  /**\n   * @param {string} text\n   * @param {string} extraName\n   * @returns {boolean}\n   */\n  const descriptionIsRedundant = (text, extraName = '') => {\n    const textTrimmed = text.trim();\n    return Boolean(textTrimmed) && !areDocsInformative(textTrimmed, [\n      extraName, nodeNames,\n    ].filter(Boolean).join(' '), {\n      aliases,\n      uselessWords,\n    });\n  };\n\n  const {\n    description,\n    lastDescriptionLine,\n  } = utils.getDescription();\n  let descriptionReported = false;\n\n  for (const tag of jsdoc.tags) {\n    if (excludedTags.includes(tag.tag)) {\n      continue;\n    }\n\n    if (descriptionIsRedundant(tag.description, tag.name)) {\n      utils.reportJSDoc(\n        'This tag description only repeats the name it describes.',\n        tag,\n      );\n    }\n\n    descriptionReported ||= tag.description === description &&\n      /** @type {import('comment-parser').Spec & {line: import('../iterateJsdoc.js').Integer}} */\n      (tag).line === lastDescriptionLine;\n  }\n\n  if (!descriptionReported && descriptionIsRedundant(description)) {\n    report('This description only repeats the name it describes.');\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description:\n        'This rule reports doc comments that only restate their attached name.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          aliases: {\n            description: `The \\`aliases\\` option allows indicating words as synonyms (aliases) of each other.\n\nFor example, with \\`{ aliases: { emoji: [\"smiley\", \"winkey\"] } }\\`, the following comment would be considered uninformative:\n\n\\`\\`\\`js\n/** A smiley/winkey. */\nlet emoji;\n\\`\\`\\`\n\nThe default \\`aliases\\` option is:\n\n\\`\\`\\`json\n{\n  \"a\": [\"an\", \"our\"]\n}\n\\`\\`\\``,\n            patternProperties: {\n              '.*': {\n                items: {\n                  type: 'string',\n                },\n                type: 'array',\n              },\n            },\n          },\n          excludedTags: {\n            description: `Tags that should not be checked for valid contents.\n\nFor example, with \\`{ excludedTags: [\"category\"] }\\`, the following comment would not be considered uninformative:\n\n\\`\\`\\`js\n/** @category Types */\nfunction computeTypes(node) {\n  // ...\n}\n\\`\\`\\`\n\nNo tags are excluded by default.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          uselessWords: {\n            description: `Words that are ignored when searching for one that adds meaning.\n\nFor example, with \\`{ uselessWords: [\"our\"] }\\`, the following comment would be considered uninformative:\n\n\\`\\`\\`js\n/** Our text. */\nlet text;\n\\`\\`\\`\n\nThe default \\`uselessWords\\` option is:\n\n\\`\\`\\`json\n[\"a\", \"an\", \"i\", \"in\", \"of\", \"s\", \"the\"]\n\\`\\`\\``,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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uE;MACzE,GAAG,EAAE;IACP,CAAC;IACD,MAAM,EAAE,CACN;MACE,oBAAoB,EAAE,KAAK;MAC3B,UAAU,EAAE;QACV,OAAO,EAAE;UACP,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO;UACK,iBAAiB,EAAE;YACjB,IAAI,EAAE;cACJ,KAAK,EAAE;gBACL,IAAI,EAAE;cACR,CAAC;cACD,IAAI,EAAE;YACR;UACF;QACF,CAAC;QACD,YAAY,EAAE;UACZ,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,iCAAiC;UACrB,KAAK,EAAE;YACL,IAAI,EAAE;UACR,CAAC;UACD,IAAI,EAAE;QACR,CAAC;QACD,YAAY,EAAE;UACZ,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO;UACK,KAAK,EAAE;YACL,IAAI,EAAE;UACR,CAAC;UACD,IAAI,EAAE;QACR;MACF,CAAC;MACD,IAAI,EAAE;IACR,CAAC,CACF;IACD,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAA","ignoreList":[]}