Skip to content

Commit b456702

Browse files
a-tarasyuka-tarasyuk
authored
feat(11378): check param names in JSDoc (microsoft#47257)
1 parent 954ce5b commit b456702

22 files changed

+779
-46
lines changed

‎src/compiler/checker.ts‎

Lines changed: 40 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -34472,6 +34472,7 @@ namespace ts {
3447234472
}
3447334473

3447434474
checkTypeParameters(getEffectiveTypeParameterDeclarations(node));
34475+
checkUnmatchedJSDocParameters(node);
3447534476

3447634477
forEach(node.parameters, checkParameter);
3447734478

@@ -36235,40 +36236,7 @@ namespace ts {
3623536236

3623636237
function checkJSDocParameterTag(node: JSDocParameterTag) {
3623736238
checkSourceElement(node.typeExpression);
36238-
if (!getParameterSymbolFromJSDoc(node)) {
36239-
const decl = getHostSignatureFromJSDoc(node);
36240-
// don't issue an error for invalid hosts -- just functions --
36241-
// and give a better error message when the host function mentions `arguments`
36242-
// but the tag doesn't have an array type
36243-
if (decl) {
36244-
const i = getJSDocTags(decl).filter(isJSDocParameterTag).indexOf(node);
36245-
if (i > -1 && i < decl.parameters.length && isBindingPattern(decl.parameters[i].name)) {
36246-
return;
36247-
}
36248-
if (!containsArgumentsReference(decl)) {
36249-
if (isQualifiedName(node.name)) {
36250-
error(node.name,
36251-
Diagnostics.Qualified_name_0_is_not_allowed_without_a_leading_param_object_1,
36252-
entityNameToString(node.name),
36253-
entityNameToString(node.name.left));
36254-
}
36255-
else {
36256-
error(node.name,
36257-
Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name,
36258-
idText(node.name));
36259-
}
36260-
}
36261-
else if (findLast(getJSDocTags(decl), isJSDocParameterTag) === node &&
36262-
node.typeExpression && node.typeExpression.type &&
36263-
!isArrayType(getTypeFromTypeNode(node.typeExpression.type))) {
36264-
error(node.name,
36265-
Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name_It_would_match_arguments_if_it_had_an_array_type,
36266-
idText(node.name.kind === SyntaxKind.QualifiedName ? node.name.right : node.name));
36267-
}
36268-
}
36269-
}
3627036239
}
36271-
3627236240
function checkJSDocPropertyTag(node: JSDocPropertyTag) {
3627336241
checkSourceElement(node.typeExpression);
3627436242
}
@@ -38564,6 +38532,45 @@ namespace ts {
3856438532
}
3856538533
}
3856638534

38535+
function checkUnmatchedJSDocParameters(node: SignatureDeclaration) {
38536+
const jsdocParameters = filter(getJSDocTags(node), isJSDocParameterTag);
38537+
if (!length(jsdocParameters)) return;
38538+
38539+
const isJs = isInJSFile(node);
38540+
const parameters = new Set<__String>();
38541+
const excludedParameters = new Set<number>();
38542+
forEach(node.parameters, ({ name }, index) => {
38543+
if (isIdentifier(name)) {
38544+
parameters.add(name.escapedText);
38545+
}
38546+
if (isBindingPattern(name)) {
38547+
excludedParameters.add(index);
38548+
}
38549+
});
38550+
38551+
const containsArguments = containsArgumentsReference(node);
38552+
if (containsArguments) {
38553+
const lastJSDocParam = lastOrUndefined(jsdocParameters);
38554+
if (lastJSDocParam && isIdentifier(lastJSDocParam.name) && lastJSDocParam.typeExpression &&
38555+
lastJSDocParam.typeExpression.type && !parameters.has(lastJSDocParam.name.escapedText) && !isArrayType(getTypeFromTypeNode(lastJSDocParam.typeExpression.type))) {
38556+
errorOrSuggestion(isJs, lastJSDocParam.name, Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name_It_would_match_arguments_if_it_had_an_array_type, idText(lastJSDocParam.name));
38557+
}
38558+
}
38559+
else {
38560+
forEach(jsdocParameters, ({ name }, index) => {
38561+
if (excludedParameters.has(index) || isIdentifier(name) && parameters.has(name.escapedText)) {
38562+
return;
38563+
}
38564+
if (isQualifiedName(name)) {
38565+
errorOrSuggestion(isJs, name, Diagnostics.Qualified_name_0_is_not_allowed_without_a_leading_param_object_1, entityNameToString(name), entityNameToString(name.left));
38566+
}
38567+
else {
38568+
errorOrSuggestion(isJs, name, Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name, idText(name));
38569+
}
38570+
});
38571+
}
38572+
}
38573+
3856738574
/**
3856838575
* Check each type parameter and check that type parameters have no duplicate type parameter declarations
3856938576
*/

‎src/compiler/diagnosticMessages.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7135,6 +7135,18 @@
71357135
"category": "Message",
71367136
"code": 95170
71377137
},
7138+
"Delete unused '@param' tag '{0}'": {
7139+
"category": "Message",
7140+
"code": 95171
7141+
},
7142+
"Delete all unused '@param' tags": {
7143+
"category": "Message",
7144+
"code": 95172
7145+
},
7146+
"Rename '@param' tag name '{0}' to '{1}'": {
7147+
"category": "Message",
7148+
"code": 95173
7149+
},
71387150

71397151
"No value exists in scope for the shorthand property '{0}'. Either declare one or provide an initializer.": {
71407152
"category": "Error",

‎src/services/codefixes/fixUnmatchedParameter.ts‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
/* @internal */
2+
namespace ts.codefix {
3+
const deleteUnmatchedParameter = "deleteUnmatchedParameter";
4+
const renameUnmatchedParameter = "renameUnmatchedParameter";
5+
6+
const errorCodes = [
7+
Diagnostics.JSDoc_param_tag_has_name_0_but_there_is_no_parameter_with_that_name.code,
8+
];
9+
10+
registerCodeFix({
11+
fixIds: [deleteUnmatchedParameter, renameUnmatchedParameter],
12+
errorCodes,
13+
getCodeActions: function getCodeActionsToFixUnmatchedParameter(context) {
14+
const { sourceFile, span } = context;
15+
const actions: CodeFixAction[] = [];
16+
const info = getInfo(sourceFile, span.start);
17+
if (info) {
18+
append(actions, getDeleteAction(context, info));
19+
append(actions, getRenameAction(context, info));
20+
return actions;
21+
}
22+
return undefined;
23+
},
24+
getAllCodeActions: function getAllCodeActionsToFixUnmatchedParameter(context) {
25+
const tagsToSignature = new Map<SignatureDeclaration, JSDocTag[]>();
26+
return createCombinedCodeActions(textChanges.ChangeTracker.with(context, changes => {
27+
eachDiagnostic(context, errorCodes, ({ file, start }) => {
28+
const info = getInfo(file, start);
29+
if (info) {
30+
tagsToSignature.set(info.signature, append(tagsToSignature.get(info.signature), info.jsDocParameterTag));
31+
}
32+
});
33+
34+
tagsToSignature.forEach((tags, signature) => {
35+
if (context.fixId === deleteUnmatchedParameter) {
36+
const tagsSet = new Set(tags);
37+
changes.filterJSDocTags(signature.getSourceFile(), signature, t => !tagsSet.has(t));
38+
}
39+
});
40+
}));
41+
}
42+
});
43+
44+
function getDeleteAction(context: CodeFixContext, { name, signature, jsDocParameterTag }: Info) {
45+
const changes = textChanges.ChangeTracker.with(context, changeTracker =>
46+
changeTracker.filterJSDocTags(context.sourceFile, signature, t => t !== jsDocParameterTag));
47+
return createCodeFixAction(
48+
deleteUnmatchedParameter,
49+
changes,
50+
[Diagnostics.Delete_unused_param_tag_0, name.getText(context.sourceFile)],
51+
deleteUnmatchedParameter,
52+
Diagnostics.Delete_all_unused_param_tags
53+
);
54+
}
55+
56+
function getRenameAction(context: CodeFixContext, { name, signature, jsDocParameterTag }: Info) {
57+
if (!length(signature.parameters)) return undefined;
58+
59+
const sourceFile = context.sourceFile;
60+
const tags = getJSDocTags(signature);
61+
const names = new Set<__String>();
62+
for (const tag of tags) {
63+
if (isJSDocParameterTag(tag) && isIdentifier(tag.name)) {
64+
names.add(tag.name.escapedText);
65+
}
66+
}
67+
// @todo - match to all available names instead to the first parameter name
68+
// @see /codeFixRenameUnmatchedParameter3.ts
69+
const parameterName = firstDefined(signature.parameters, p =>
70+
isIdentifier(p.name) && !names.has(p.name.escapedText) ? p.name.getText(sourceFile) : undefined);
71+
if (parameterName === undefined) return undefined;
72+
73+
const newJSDocParameterTag = factory.updateJSDocParameterTag(
74+
jsDocParameterTag,
75+
jsDocParameterTag.tagName,
76+
factory.createIdentifier(parameterName),
77+
jsDocParameterTag.isBracketed,
78+
jsDocParameterTag.typeExpression,
79+
jsDocParameterTag.isNameFirst,
80+
jsDocParameterTag.comment
81+
);
82+
const changes = textChanges.ChangeTracker.with(context, changeTracker =>
83+
changeTracker.replaceJSDocComment(sourceFile, signature, map(tags, t => t === jsDocParameterTag ? newJSDocParameterTag : t)));
84+
return createCodeFixActionWithoutFixAll(renameUnmatchedParameter, changes, [Diagnostics.Rename_param_tag_name_0_to_1, name.getText(sourceFile), parameterName]);
85+
}
86+
87+
interface Info {
88+
readonly signature: SignatureDeclaration;
89+
readonly jsDocParameterTag: JSDocParameterTag;
90+
readonly name: Identifier;
91+
}
92+
93+
function getInfo(sourceFile: SourceFile, pos: number): Info | undefined {
94+
const token = getTokenAtPosition(sourceFile, pos);
95+
if (token.parent && isJSDocParameterTag(token.parent) && isIdentifier(token.parent.name)) {
96+
const jsDocParameterTag = token.parent;
97+
const signature = getHostSignatureFromJSDoc(jsDocParameterTag);
98+
if (signature) {
99+
return { signature, name: token.parent.name, jsDocParameterTag };
100+
}
101+
}
102+
return undefined;
103+
}
104+
}

‎src/services/textChanges.ts‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -495,29 +495,30 @@ namespace ts.textChanges {
495495
this.insertNodeAt(sourceFile, fnStart, tag, { preserveLeadingWhitespace: false, suffix: this.newLineCharacter + indent });
496496
}
497497

498+
private createJSDocText(sourceFile: SourceFile, node: HasJSDoc) {
499+
const comments = flatMap(node.jsDoc, jsDoc =>
500+
isString(jsDoc.comment) ? factory.createJSDocText(jsDoc.comment) : jsDoc.comment) as JSDocComment[];
501+
const jsDoc = singleOrUndefined(node.jsDoc);
502+
return jsDoc && positionsAreOnSameLine(jsDoc.pos, jsDoc.end, sourceFile) && length(comments) === 0 ? undefined :
503+
factory.createNodeArray(intersperse(comments, factory.createJSDocText("\n")));
504+
}
505+
506+
public replaceJSDocComment(sourceFile: SourceFile, node: HasJSDoc, tags: readonly JSDocTag[]) {
507+
this.insertJsdocCommentBefore(sourceFile, updateJSDocHost(node), factory.createJSDocComment(this.createJSDocText(sourceFile, node), factory.createNodeArray(tags)));
508+
}
509+
498510
public addJSDocTags(sourceFile: SourceFile, parent: HasJSDoc, newTags: readonly JSDocTag[]): void {
499-
const comments = flatMap(parent.jsDoc, j => typeof j.comment === "string" ? factory.createJSDocText(j.comment) : j.comment) as JSDocComment[];
500511
const oldTags = flatMapToMutable(parent.jsDoc, j => j.tags);
501512
const unmergedNewTags = newTags.filter(newTag => !oldTags.some((tag, i) => {
502513
const merged = tryMergeJsdocTags(tag, newTag);
503514
if (merged) oldTags[i] = merged;
504515
return !!merged;
505516
}));
506-
const tags = [...oldTags, ...unmergedNewTags];
507-
const jsDoc = singleOrUndefined(parent.jsDoc);
508-
const comment = jsDoc && positionsAreOnSameLine(jsDoc.pos, jsDoc.end, sourceFile) && !length(comments) ? undefined :
509-
factory.createNodeArray(intersperse(comments, factory.createJSDocText("\n")));
510-
const tag = factory.createJSDocComment(comment, factory.createNodeArray(tags));
511-
const host = updateJSDocHost(parent);
512-
this.insertJsdocCommentBefore(sourceFile, host, tag);
517+
this.replaceJSDocComment(sourceFile, parent, [...oldTags, ...unmergedNewTags]);
513518
}
514519

515520
public filterJSDocTags(sourceFile: SourceFile, parent: HasJSDoc, predicate: (tag: JSDocTag) => boolean): void {
516-
const comments = flatMap(parent.jsDoc, j => typeof j.comment === "string" ? factory.createJSDocText(j.comment) : j.comment) as JSDocComment[];
517-
const oldTags = flatMapToMutable(parent.jsDoc, j => j.tags);
518-
const tag = factory.createJSDocComment(factory.createNodeArray(intersperse(comments, factory.createJSDocText("\n"))), factory.createNodeArray([...(filter(oldTags, predicate) || emptyArray)]));
519-
const host = updateJSDocHost(parent);
520-
this.insertJsdocCommentBefore(sourceFile, host, tag);
521+
this.replaceJSDocComment(sourceFile, parent, filter(flatMapToMutable(parent.jsDoc, j => j.tags), predicate));
521522
}
522523

523524
public replaceRangeWithText(sourceFile: SourceFile, range: TextRange, text: string): void {

‎src/services/tsconfig.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787
"codefixes/fixExtendsInterfaceBecomesImplements.ts",
8888
"codefixes/fixForgottenThisPropertyAccess.ts",
8989
"codefixes/fixInvalidJsxCharacters.ts",
90+
"codefixes/fixUnmatchedParameter.ts",
9091
"codefixes/fixUnusedIdentifier.ts",
9192
"codefixes/fixUnreachableCode.ts",
9293
"codefixes/fixUnusedLabel.ts",

‎tests/baselines/reference/checkJsdocParamOnVariableDeclaredFunctionExpression.errors.txt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
tests/cases/conformance/jsdoc/0.js(14,20): error TS8024: JSDoc '@param' tag has name 's', but there is no parameter with that name.
2+
3+
4+
==== tests/cases/conformance/jsdoc/0.js (1 errors) ====
5+
// @ts-check
6+
/**
7+
* @param {number=} n
8+
* @param {string} [s]
9+
*/
10+
var x = function foo(n, s) {}
11+
var y;
12+
/**
13+
* @param {boolean!} b
14+
*/
15+
y = function bar(b) {}
16+
17+
/**
18+
* @param {string} s
19+
~
20+
!!! error TS8024: JSDoc '@param' tag has name 's', but there is no parameter with that name.
21+
*/
22+
var one = function (s) { }, two = function (untyped) { };
23+

‎tests/cases/fourslash/codeFixDeleteUnmatchedParameter1.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/// <reference path='fourslash.ts' />
2+
3+
// @filename: a.ts
4+
/////**
5+
//// * @param {number} a
6+
//// * @param {number} b
7+
//// */
8+
////function foo() {}
9+
10+
verify.codeFixAvailable([
11+
{ description: "Delete unused '@param' tag 'a'" },
12+
{ description: "Delete unused '@param' tag 'b'" },
13+
]);
14+
15+
verify.codeFix({
16+
description: [ts.Diagnostics.Delete_unused_param_tag_0.message, "a"],
17+
index: 0,
18+
newFileContent:
19+
`/**
20+
* @param {number} b
21+
*/
22+
function foo() {}`,
23+
});

‎tests/cases/fourslash/codeFixDeleteUnmatchedParameter2.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
/// <reference path='fourslash.ts' />
2+
3+
// @filename: a.ts
4+
/////**
5+
//// * @param {number} a
6+
//// * @param {string} b
7+
//// */
8+
////function foo(a: number) {
9+
//// a;
10+
////}
11+
12+
verify.codeFixAvailable([
13+
{ description: "Delete unused '@param' tag 'b'" },
14+
]);
15+
16+
verify.codeFix({
17+
description: [ts.Diagnostics.Delete_unused_param_tag_0.message, "b"],
18+
index: 0,
19+
newFileContent:
20+
`/**
21+
* @param {number} a
22+
*/
23+
function foo(a: number) {
24+
a;
25+
}`
26+
});

‎tests/cases/fourslash/codeFixDeleteUnmatchedParameter3.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/// <reference path='fourslash.ts' />
2+
3+
// @filename: a.ts
4+
/////**
5+
//// * @param {number} a
6+
//// * @param {string} b
7+
//// * @param {number} c
8+
//// */
9+
////function foo(a: number, c: number) {
10+
//// a;
11+
//// c;
12+
////}
13+
14+
verify.codeFixAvailable([
15+
{ description: "Delete unused '@param' tag 'b'" },
16+
]);
17+
18+
verify.codeFix({
19+
description: [ts.Diagnostics.Delete_unused_param_tag_0.message, "b"],
20+
index: 0,
21+
newFileContent:
22+
`/**
23+
* @param {number} a
24+
* @param {number} c
25+
*/
26+
function foo(a: number, c: number) {
27+
a;
28+
c;
29+
}`
30+
});

‎tests/cases/fourslash/codeFixDeleteUnmatchedParameter4.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/// <reference path='fourslash.ts' />
2+
3+
// @filename: a.ts
4+
/////**
5+
//// * @param {number} a
6+
//// */
7+
////function foo() {}
8+
9+
verify.codeFixAvailable([
10+
{ description: "Delete unused '@param' tag 'a'" },
11+
]);
12+
13+
verify.codeFix({
14+
description: [ts.Diagnostics.Delete_unused_param_tag_0.message, "a"],
15+
index: 0,
16+
newFileContent:
17+
`/** */
18+
function foo() {}`
19+
});

0 commit comments

Comments
 (0)