eslint-plugin-jsdoc 46.5.1 → 46.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -65,8 +65,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
65
65
|
report,
|
|
66
66
|
utils
|
|
67
67
|
}) => {
|
|
68
|
-
const {
|
|
68
|
+
const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */{
|
|
69
69
|
aliases = defaultAliases,
|
|
70
|
+
excludedTags = [],
|
|
70
71
|
uselessWords = defaultUselessWords
|
|
71
72
|
} = context.options[0] || {};
|
|
72
73
|
const nodeNames = getNamesFromNode(node);
|
|
@@ -89,6 +90,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
89
90
|
} = utils.getDescription();
|
|
90
91
|
let descriptionReported = false;
|
|
91
92
|
for (const tag of jsdoc.tags) {
|
|
93
|
+
if (excludedTags.includes(tag.tag)) {
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
92
96
|
if (descriptionIsRedundant(tag.description, tag.name)) {
|
|
93
97
|
utils.reportJSDoc('This tag description only repeats the name it describes.', tag);
|
|
94
98
|
}
|
|
@@ -109,6 +113,16 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
109
113
|
additionalProperties: false,
|
|
110
114
|
properties: {
|
|
111
115
|
aliases: {
|
|
116
|
+
patternProperties: {
|
|
117
|
+
'.*': {
|
|
118
|
+
items: {
|
|
119
|
+
type: 'string'
|
|
120
|
+
},
|
|
121
|
+
type: 'array'
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
},
|
|
125
|
+
excludedTags: {
|
|
112
126
|
items: {
|
|
113
127
|
type: 'string'
|
|
114
128
|
},
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"informativeDocs.js","names":["_iterateJsdoc","_interopRequireDefault","require","_areDocsInformative","obj","__esModule","default","defaultAliases","a","defaultUselessWords","getNamesFromNode","node","type","parent","key","id","name","declarations","init","filter","Boolean","_default","iterateJsdoc","context","jsdoc","report","utils","aliases","uselessWords","options","nodeNames","descriptionIsRedundant","text","extraName","textTrimmed","trim","areDocsInformative","join","description","lastDescriptionLine","getDescription","descriptionReported","tag","tags","reportJSDoc","line","iterateAllJsdocs","meta","docs","url","schema","additionalProperties","properties","items","exports","module"],"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/* eslint-disable complexity -- Temporary */\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 case 'ClassDeclaration':\n case 'ClassExpression':\n case 'FunctionDeclaration':\n case 'FunctionExpression':\n case 'TSModuleDeclaration':\n case 'TSMethodSignature':\n case 'TSDeclareFunction':\n case 'TSEnumDeclaration':\n case 'TSEnumMember':\n case 'TSInterfaceDeclaration':\n case 'TSTypeAliasDeclaration':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */\n (node).id,\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/* eslint-enable complexity -- Temporary */\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n node,\n report,\n utils,\n}) => {\n const {\n aliases = defaultAliases,\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 (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 items: {\n type: 'string',\n },\n type: 'array',\n },\n uselessWords: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AAE8B,SAAAD,uBAAAG,GAAA,WAAAA,GAAA,IAAAA,GAAA,CAAAC,UAAA,GAAAD,GAAA,KAAAE,OAAA,EAAAF,GAAA;AAE9B,MAAMG,cAAc,GAAG;EACrBC,CAAC,EAAE,CACD,IAAI,EAAE,KAAK;AAEf,CAAC;AAED,MAAMC,mBAAmB,GAAG,CAC1B,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CACvC;;AAED;;AAEA;AACA;AACA;AACA;AACA,MAAMC,gBAAgB,GAAIC,IAAI,IAAK;EACjC,QAAQA,IAAI,aAAJA,IAAI,uBAAJA,IAAI,CAAEC,IAAI;IAClB,KAAK,kBAAkB;IACvB,KAAK,kBAAkB;IACvB,KAAK,oBAAoB;IACzB,KAAK,4BAA4B;IACjC,KAAK,4BAA4B;IACjC,KAAK,8BAA8B;MACjC,OAAO,CACL,GAAGF,gBAAgB,EACjB,+DACEC,IAAI,CAACE,MAAM,CACXA,MACJ,CAAC,EACD,GAAGH,gBAAgB,EACjB;MACCC,IAAI,CAACG,GACR,CAAC,CACF;IACH,KAAK,kBAAkB;IACvB,KAAK,iBAAiB;IACtB,KAAK,qBAAqB;IAC1B,KAAK,oBAAoB;IACzB,KAAK,qBAAqB;IAC1B,KAAK,mBAAmB;IACxB,KAAK,mBAAmB;IACxB,KAAK,mBAAmB;IACxB,KAAK,cAAc;IACnB,KAAK,wBAAwB;IAC7B,KAAK,wBAAwB;MAC3B,OAAOJ,gBAAgB,EACrB;MACCC,IAAI,CAAEI,EACT,CAAC;IACH,KAAK,YAAY;MACf,OAAO,CACLJ,IAAI,CAACK,IAAI,CACV;IACH,KAAK,UAAU;MACb,OAAON,gBAAgB,EACrB;MACCC,IAAI,CAACG,GACR,CAAC;IACH,KAAK,qBAAqB;MACxB,OAAOJ,gBAAgB,EACrB;MACCC,IAAI,CAACM,YAAY,CAAC,CAAC,CACtB,CAAC;IACH,KAAK,oBAAoB;MACvB,OAAO,CACL,GAAGP,gBAAgB,EACjB;MACCC,IAAI,CAACI,EACR,CAAC,EACD,GAAGL,gBAAgB,EACjB;MACCC,IAAI,CAACO,IACR,CAAC,CACF,CAACC,MAAM,CAACC,OAAO,CAAC;IACnB;MACE,OAAO,EAAE;EACX;AACF,CAAC;AACD;AAAA,IAAAC,QAAA,GAEe,IAAAC,qBAAY,EAAC,CAAC;EAC3BC,OAAO;EACPC,KAAK;EACLb,IAAI;EACJc,MAAM;EACNC;AACF,CAAC,KAAK;EACJ,MAAM;
|
|
1
|
+
{"version":3,"file":"informativeDocs.js","names":["_iterateJsdoc","_interopRequireDefault","require","_areDocsInformative","obj","__esModule","default","defaultAliases","a","defaultUselessWords","getNamesFromNode","node","type","parent","key","id","name","declarations","init","filter","Boolean","_default","iterateJsdoc","context","jsdoc","report","utils","aliases","excludedTags","uselessWords","options","nodeNames","descriptionIsRedundant","text","extraName","textTrimmed","trim","areDocsInformative","join","description","lastDescriptionLine","getDescription","descriptionReported","tag","tags","includes","reportJSDoc","line","iterateAllJsdocs","meta","docs","url","schema","additionalProperties","properties","patternProperties","items","exports","module"],"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/* eslint-disable complexity -- Temporary */\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 case 'ClassDeclaration':\n case 'ClassExpression':\n case 'FunctionDeclaration':\n case 'FunctionExpression':\n case 'TSModuleDeclaration':\n case 'TSMethodSignature':\n case 'TSDeclareFunction':\n case 'TSEnumDeclaration':\n case 'TSEnumMember':\n case 'TSInterfaceDeclaration':\n case 'TSTypeAliasDeclaration':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */\n (node).id,\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/* eslint-enable complexity -- Temporary */\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 patternProperties: {\n '.*': {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n },\n excludedTags: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n uselessWords: {\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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"}
|
package/package.json
CHANGED