Skip to content

Commit dd0c4bb

Browse files
brettz9brettz9
committed
refactor: ts
1 parent 6ed61d6 commit dd0c4bb

File tree

10 files changed

+362
-113
lines changed

10 files changed

+362
-113
lines changed

‎docs/rules/require-jsdoc.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1825,7 +1825,7 @@ var a = {
18251825
b: 1,
18261826
c: 2
18271827
};
1828-
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":[{"context":"FunctionDeclaration","minLineCount":4},{"context":"VariableDeclaration","minLineCount":5}],"require":{"FunctionDeclaration":false}}]
1828+
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ClassDeclaration",{"context":"FunctionDeclaration","minLineCount":4},{"context":"VariableDeclaration","minLineCount":5}],"require":{"FunctionDeclaration":false}}]
18291829

18301830
class A {
18311831
setId(newId: number): void {

‎src/iterateJsdoc.js

Lines changed: 59 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@ import jsdocUtils from './jsdocUtils';
1717
* @callback CheckJsdoc
1818
* @param {{
1919
* lastIndex?: Integer,
20-
* selector: string
20+
* isFunctionContext?: boolean,
21+
* selector?: string
2122
* }} info
22-
* @param {(jsdoc: import('comment-parser').Block) => boolean|undefined} handler
23+
* @param {null|((jsdoc: import('comment-parser').Block) => boolean|undefined)} handler
2324
* @param {import('eslint').Rule.Node} node
2425
* @returns {void}
2526
*/
@@ -97,8 +98,8 @@ import jsdocUtils from './jsdocUtils';
9798
* @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} tag
9899
* @param {(() => void)|null} handler
99100
* @param {boolean} [specRewire]
100-
* @param {{
101-
* [key: string]: undefined|string
101+
* @param {undefined|{
102+
* [key: string]: string
102103
* }} [data]
103104
*/
104105
/* eslint-enable jsdoc/valid-types -- Old version */
@@ -218,12 +219,14 @@ import jsdocUtils from './jsdocUtils';
218219
* @returns {void}
219220
*/
220221

222+
/* eslint-disable jsdoc/no-undefined-types -- TS */
221223
/**
222224
* @callback AddLine
223225
* @param {Integer} sourceIndex
224-
* @param {import('comment-parser').Tokens} tokens
226+
* @param {Partial<import('comment-parser').Tokens>} tokens
225227
* @returns {void}
226228
*/
229+
/* eslint-enable jsdoc/no-undefined-types -- TS */
227230

228231
/**
229232
* @callback AddLines
@@ -241,7 +244,7 @@ import jsdocUtils from './jsdocUtils';
241244
/**
242245
* @callback GetFunctionParameterNames
243246
* @param {boolean} [useDefaultObjectProperties]
244-
* @returns {}
247+
* @returns {import('./jsdocUtils.js').ParamNameInfo[]}
245248
*/
246249

247250
/**
@@ -346,7 +349,7 @@ import jsdocUtils from './jsdocUtils';
346349
/**
347350
* @callback IsNamepathX
348351
* @param {string} tagName
349-
* @returns {}
352+
* @returns {boolean}
350353
*/
351354

352355
/**
@@ -403,10 +406,17 @@ import jsdocUtils from './jsdocUtils';
403406
/**
404407
* @callback FilterTags
405408
* @param {(tag: import('comment-parser').Spec) => boolean} filter
406-
* @param {boolean} [includeInlineTags]
407409
* @returns {import('comment-parser').Spec[]}
408410
*/
409411

412+
/**
413+
* @callback FilterAllTags
414+
* @param {(tag: (import('comment-parser').Spec|
415+
* import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter
416+
* @returns {(import('comment-parser').Spec|
417+
* import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
418+
*/
419+
410420
/**
411421
* @callback GetTagsByType
412422
* @param {import('comment-parser').Spec[]} tags
@@ -494,6 +504,7 @@ import jsdocUtils from './jsdocUtils';
494504
* getTags: GetTags,
495505
* getPresentTags: GetPresentTags,
496506
* filterTags: FilterTags,
507+
* filterAllTags: FilterAllTags,
497508
* getTagsByType: GetTagsByType,
498509
* hasOptionTag: HasOptionTag,
499510
* getClassNode: GetClassNode,
@@ -659,7 +670,7 @@ const getUtils = (
659670
ruleConfig,
660671
indent,
661672
) => {
662-
const ancestors = context.getAncestors();
673+
const ancestors = /** @type {import('eslint').Rule.Node[]} */ (context.getAncestors());
663674
const sourceCode = context.getSourceCode();
664675

665676
const utils = /** @type {Utils} */ (getBasicUtils(context, settings));
@@ -1213,11 +1224,12 @@ const getUtils = (
12131224
// istanbul ignore next
12141225
return false;
12151226
});
1227+
12161228
for (const [
12171229
idx,
12181230
src,
12191231
] of jsdoc.source.slice(lastIndex).entries()) {
1220-
src.number = firstNumber + lastIndex + idx;
1232+
src.number = firstNumber + /** @type {Integer} */ (lastIndex) + idx;
12211233
}
12221234
};
12231235

@@ -1299,13 +1311,22 @@ const getUtils = (
12991311

13001312
/** @type {IsGenerator} */
13011313
utils.isGenerator = () => {
1302-
return node && (
1303-
node.generator ||
1314+
return node && Boolean(
1315+
/**
1316+
* @type {import('estree').FunctionDeclaration|
1317+
* import('estree').FunctionExpression}
1318+
*/ (node).generator ||
13041319
node.type === 'MethodDefinition' && node.value.generator ||
13051320
[
13061321
'ExportNamedDeclaration', 'ExportDefaultDeclaration',
13071322
].includes(node.type) &&
1308-
node.declaration.generator
1323+
/** @type {import('estree').FunctionDeclaration} */
1324+
(
1325+
/**
1326+
* @type {import('estree').ExportNamedDeclaration|
1327+
* import('estree').ExportDefaultDeclaration}
1328+
*/ (node).declaration
1329+
).generator,
13091330
);
13101331
};
13111332

@@ -1397,7 +1418,12 @@ const getUtils = (
13971418
}
13981419

13991420
if (jsdocUtils.exemptSpeciaMethods(
1400-
jsdoc, node, context, ruleConfig.meta.schema,
1421+
jsdoc,
1422+
node,
1423+
context,
1424+
/** @type {import('json-schema').JSONSchema4|import('json-schema').JSONSchema4[]} */ (
1425+
ruleConfig.meta.schema
1426+
),
14011427
)) {
14021428
return true;
14031429
}
@@ -1536,7 +1562,12 @@ const getUtils = (
15361562
if ([
15371563
'ExportNamedDeclaration', 'ExportDefaultDeclaration',
15381564
].includes(node.type)) {
1539-
return jsdocUtils.hasYieldValue(node.declaration);
1565+
return jsdocUtils.hasYieldValue(
1566+
/** @type {import('estree').Declaration|import('estree').Expression} */ (
1567+
/** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
1568+
(node).declaration
1569+
),
1570+
);
15401571
}
15411572

15421573
return jsdocUtils.hasYieldValue(node);
@@ -1572,9 +1603,18 @@ const getUtils = (
15721603
};
15731604

15741605
/** @type {FilterTags} */
1575-
utils.filterTags = (filter, includeInlineTags = false) => {
1576-
const tags = jsdocUtils.getAllTags(jsdoc, includeInlineTags);
1577-
return jsdocUtils.filterTags(tags, filter);
1606+
utils.filterTags = (filter) => {
1607+
return jsdoc.tags.filter((tag) => {
1608+
return filter(tag);
1609+
});
1610+
};
1611+
1612+
/** @type {FilterAllTags} */
1613+
utils.filterAllTags = (filter) => {
1614+
const tags = jsdocUtils.getAllTags(jsdoc);
1615+
return tags.filter((tag) => {
1616+
return filter(tag);
1617+
});
15781618
};
15791619

15801620
/** @type {GetTagsByType} */
@@ -1734,7 +1774,7 @@ const getSettings = (context) => {
17341774
*
17351775
* @callback MakeReport
17361776
* @param {import('eslint').Rule.RuleContext} context
1737-
* @param {object} commentNode
1777+
* @param {import('@es-joy/jsdoccomment').Token} commentNode
17381778
* @returns {Report}
17391779
*/
17401780

‎src/jsdocUtils.js

Lines changed: 56 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,20 @@ const setTagStructure = (mode) => {
4747
*/
4848

4949
/**
50-
* @typedef {string|{
50+
* @typedef {undefined|string|{
51+
* isRestProperty: boolean|undefined,
52+
* name: string,
53+
* restElement: true
54+
* }|[undefined|string, FlattendRootInfo & {
55+
* annotationParamName?: string
56+
* }|{
57+
* name: Integer,
58+
* restElement: boolean
59+
* }[]]} ParamNameInfo
60+
*/
61+
62+
/**
63+
* @typedef {undefined|string|{
5164
* isRestProperty: boolean,
5265
* restElement: boolean,
5366
* name: string
@@ -188,17 +201,6 @@ const getPropertiesFromPropertySignature = (propSignature) => {
188201
).name;
189202
};
190203

191-
/**
192-
* @typedef {undefined|{
193-
* isRestProperty: boolean|undefined,
194-
* name: string,
195-
* restElement: true
196-
* }|[undefined|string, FlattendRootInfo|{
197-
* name: Integer,
198-
* restElement: boolean
199-
* }[]]} ParamNameInfo
200-
*/
201-
202204
/**
203205
* @param {ESTreeOrTypeScriptNode} functionNode
204206
* @param {boolean} [checkDefaultObjects]
@@ -213,7 +215,9 @@ const getFunctionParameterNames = (
213215
* @param {import('estree').Identifier|import('estree').AssignmentPattern|
214216
* import('estree').ObjectPattern|import('estree').Property|
215217
* import('estree').RestElement|import('estree').ArrayPattern|
216-
* import('@typescript-eslint/types').TSESTree.TSParameterProperty
218+
* import('@typescript-eslint/types').TSESTree.TSParameterProperty|
219+
* import('@typescript-eslint/types').TSESTree.Property|
220+
* import('@typescript-eslint/types').TSESTree.RestElement
217221
* } param
218222
* @param {boolean} [isProperty]
219223
* @returns {ParamNameInfo}
@@ -226,21 +230,34 @@ const getFunctionParameterNames = (
226230
const typeAnnotation = hasLeftTypeAnnotation ?
227231
/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
228232
param.left
229-
).typeAnnotation : param.typeAnnotation;
233+
).typeAnnotation :
234+
/** @type {import('@typescript-eslint/types').TSESTree.Identifier|import('@typescript-eslint/types').TSESTree.ObjectPattern} */
235+
(param).typeAnnotation;
230236

231237
if (typeAnnotation?.typeAnnotation?.type === 'TSTypeLiteral') {
232238
const propertyNames = typeAnnotation.typeAnnotation.members.map((member) => {
233-
return getPropertiesFromPropertySignature(member);
239+
return getPropertiesFromPropertySignature(
240+
/** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
241+
(member),
242+
);
234243
});
244+
235245
const flattened = {
236246
...flattenRoots(propertyNames),
237-
annotationParamName: param.name,
247+
annotationParamName: 'name' in param ? param.name : undefined,
238248
};
239249
const hasLeftName = 'left' in param && 'name' in param.left;
240250

241251
if ('name' in param || hasLeftName) {
242252
return [
243-
hasLeftName ? param.left.name : param.name, flattened,
253+
hasLeftName ?
254+
/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
255+
param.left
256+
).name :
257+
/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
258+
param
259+
).name,
260+
flattened,
244261
];
245262
}
246263

@@ -258,8 +275,22 @@ const getFunctionParameterNames = (
258275
return param.left.name;
259276
}
260277

261-
if (param.type === 'ObjectPattern' || param.left?.type === 'ObjectPattern') {
262-
const properties = param.properties || param.left?.properties;
278+
if (
279+
param.type === 'ObjectPattern' ||
280+
('left' in param &&
281+
(
282+
param
283+
).left.type === 'ObjectPattern')
284+
) {
285+
const properties = /** @type {import('@typescript-eslint/types').TSESTree.ObjectPattern} */ (
286+
param
287+
).properties ||
288+
/** @type {import('estree').ObjectPattern} */
289+
(
290+
/** @type {import('@typescript-eslint/types').TSESTree.AssignmentPattern} */ (
291+
param
292+
).left
293+
)?.properties;
263294
const roots = properties.map((prop) => {
264295
return getParamName(prop, true);
265296
});
@@ -557,7 +588,7 @@ const isValidTag = (
557588
};
558589

559590
/**
560-
* @param {object} jsdoc
591+
* @param {import('comment-parser').Block} jsdoc
561592
* @param {string} targetTagName
562593
* @returns {boolean}
563594
*/
@@ -575,12 +606,11 @@ const hasTag = (jsdoc, targetTagName) => {
575606
* @param {import('comment-parser').Block & {
576607
* inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
577608
* }} jsdoc
578-
* @param {boolean} includeInlineTags
579609
* @returns {(import('comment-parser').Spec|
580610
* import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
581611
*/
582-
const getAllTags = (jsdoc, includeInlineTags) => {
583-
return includeInlineTags ? [
612+
const getAllTags = (jsdoc) => {
613+
return [
584614
...jsdoc.tags,
585615
...jsdoc.inlineTags.map((inlineTag) => {
586616
// Tags don't have source or line numbers, so add before returning
@@ -640,11 +670,11 @@ const getAllTags = (jsdoc, includeInlineTags) => {
640670
).inlineTags
641671
);
642672
}),
643-
] : jsdoc.tags;
673+
];
644674
};
645675

646676
/**
647-
* @param {object} jsdoc
677+
* @param {import('comment-parser').Block} jsdoc
648678
* @param {string[]} targetTagNames
649679
* @returns {boolean}
650680
*/
@@ -1293,17 +1323,6 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
12931323
return properties;
12941324
};
12951325

1296-
/**
1297-
* @param {import('comment-parser').Spec[]} tags
1298-
* @param {(tag: import('comment-parser').Spec) => boolean} filter
1299-
* @returns {import('comment-parser').Spec[]}
1300-
*/
1301-
const filterTags = (tags, filter) => {
1302-
return tags.filter((tag) => {
1303-
return filter(tag);
1304-
});
1305-
};
1306-
13071326
const tagsWithNamesAndDescriptions = new Set([
13081327
'param', 'arg', 'argument', 'property', 'prop',
13091328
'template',
@@ -1337,7 +1356,7 @@ const getTagsByType = (context, mode, tags, tagPreference) => {
13371356
* @type {import('comment-parser').Spec[]}
13381357
*/
13391358
const tagsWithoutNames = [];
1340-
const tagsWithNames = filterTags(tags, (tag) => {
1359+
const tagsWithNames = tags.filter((tag) => {
13411360
const {
13421361
tag: tagName,
13431362
} = tag;
@@ -1522,7 +1541,6 @@ export default {
15221541
dropPathSegmentQuotes,
15231542
enforcedContexts,
15241543
exemptSpeciaMethods,
1525-
filterTags,
15261544
flattenRoots,
15271545
getAllTags,
15281546
getContextObject,

0 commit comments

Comments
 (0)