diff --git a/src/compiler/parser.ts b/src/compiler/parser.ts index 2d0a4b66a1..342414da84 100644 --- a/src/compiler/parser.ts +++ b/src/compiler/parser.ts @@ -6510,7 +6510,7 @@ namespace ts { case "arg": case "argument": case "param": - tag = parseParamTag(atToken, tagName); + tag = parseParameterOrPropertyTag(atToken, tagName, /*shouldParseParamTag*/ true); break; case "return": case "returns": @@ -6655,11 +6655,12 @@ namespace ts { return { name, isBracketed }; } - function parseParamTag(atToken: AtToken, tagName: Identifier) { + function parseParameterOrPropertyTag(atToken: AtToken, tagName: Identifier, shouldParseParamTag: boolean): JSDocPropertyTag | JSDocParameterTag { let typeExpression = tryParseTypeExpression(); skipWhitespace(); const { name, isBracketed } = parseBracketNameInPropertyAndParamTag(); + skipWhitespace(); if (!name) { parseErrorAtPosition(scanner.getStartPos(), 0, Diagnostics.Identifier_expected); @@ -6678,13 +6679,15 @@ namespace ts { typeExpression = tryParseTypeExpression(); } - const result = createNode(SyntaxKind.JSDocParameterTag, atToken.pos); + const result = shouldParseParamTag ? + createNode(SyntaxKind.JSDocParameterTag, atToken.pos) : + createNode(SyntaxKind.JSDocPropertyTag, atToken.pos); result.atToken = atToken; result.tagName = tagName; result.preParameterName = preName; result.typeExpression = typeExpression; result.postParameterName = postName; - result.parameterName = postName || preName; + result.name = postName || preName; result.isBracketed = isBracketed; return finishNode(result); } @@ -6713,26 +6716,6 @@ namespace ts { return finishNode(result); } - function parsePropertyTag(atToken: AtToken, tagName: Identifier): JSDocPropertyTag { - const typeExpression = tryParseTypeExpression(); - skipWhitespace(); - const { name, isBracketed } = parseBracketNameInPropertyAndParamTag(); - skipWhitespace(); - - if (!name) { - parseErrorAtPosition(scanner.getStartPos(), /*length*/ 0, Diagnostics.Identifier_expected); - return undefined; - } - - const result = createNode(SyntaxKind.JSDocPropertyTag, atToken.pos); - result.atToken = atToken; - result.tagName = tagName; - result.name = name; - result.typeExpression = typeExpression; - result.isBracketed = isBracketed; - return finishNode(result); - } - function parseAugmentsTag(atToken: AtToken, tagName: Identifier): JSDocAugmentsTag { const typeExpression = tryParseTypeExpression(); @@ -6869,7 +6852,7 @@ namespace ts { return true; case "prop": case "property": - const propertyTag = parsePropertyTag(atToken, tagName); + const propertyTag = parseParameterOrPropertyTag(atToken, tagName, /*shouldParseParamTag*/ false) as JSDocPropertyTag; if (propertyTag) { if (!parentTag.jsDocPropertyTags) { parentTag.jsDocPropertyTags = >[]; diff --git a/src/compiler/types.ts b/src/compiler/types.ts index 6f602ff23a..ebb0f02f39 100644 --- a/src/compiler/types.ts +++ b/src/compiler/types.ts @@ -2145,6 +2145,10 @@ namespace ts { parent: JSDoc; kind: SyntaxKind.JSDocPropertyTag; name: Identifier; + /** the parameter name, if provided *before* the type (TypeScript-style) */ + preParameterName?: Identifier; + /** the parameter name, if provided *after* the type (JSDoc-standard) */ + postParameterName?: Identifier; typeExpression: JSDocTypeExpression; isBracketed: boolean; } @@ -2163,7 +2167,7 @@ namespace ts { /** the parameter name, if provided *after* the type (JSDoc-standard) */ postParameterName?: Identifier; /** the parameter name, regardless of the location it was provided */ - parameterName: Identifier; + name: Identifier; isBracketed: boolean; } diff --git a/src/compiler/utilities.ts b/src/compiler/utilities.ts index 134404c247..506d2728ff 100644 --- a/src/compiler/utilities.ts +++ b/src/compiler/utilities.ts @@ -1635,7 +1635,7 @@ namespace ts { } else if (param.name.kind === SyntaxKind.Identifier) { const name = (param.name as Identifier).text; - return filter(tags, tag => tag.kind === SyntaxKind.JSDocParameterTag && tag.parameterName.text === name); + return filter(tags, tag => tag.kind === SyntaxKind.JSDocParameterTag && tag.name.text === name); } else { // TODO: it's a destructured parameter, so it should look up an "object type" series of multiple lines @@ -1646,7 +1646,7 @@ namespace ts { /** Does the opposite of `getJSDocParameterTags`: given a JSDoc parameter, finds the parameter corresponding to it. */ export function getParameterFromJSDoc(node: JSDocParameterTag): ParameterDeclaration | undefined { - const name = node.parameterName.text; + const name = node.name.text; const grandParent = node.parent!.parent!; Debug.assert(node.parent!.kind === SyntaxKind.JSDocComment); if (!isFunctionLike(grandParent)) { diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argSynonymForParamTag.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argSynonymForParamTag.json index 064a040c58..92b9cb450e 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argSynonymForParamTag.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argSynonymForParamTag.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 27, + "end": 28, "atToken": { "kind": "AtToken", "pos": 8, @@ -34,7 +34,7 @@ "end": 27, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 22, "end": 27, @@ -44,6 +44,6 @@ }, "length": 1, "pos": 8, - "end": 27 + "end": 28 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argumentSynonymForParamTag.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argumentSynonymForParamTag.json index 264b585022..f398fb3af4 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argumentSynonymForParamTag.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argumentSynonymForParamTag.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 32, + "end": 33, "atToken": { "kind": "AtToken", "pos": 8, @@ -34,7 +34,7 @@ "end": 32, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 27, "end": 32, @@ -44,6 +44,6 @@ }, "length": 1, "pos": 8, - "end": 32 + "end": 33 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.oneParamTag.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.oneParamTag.json index 9d303955ab..e70fc95367 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.oneParamTag.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.oneParamTag.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 29, + "end": 30, "atToken": { "kind": "AtToken", "pos": 8, @@ -34,7 +34,7 @@ "end": 29, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 24, "end": 29, @@ -44,6 +44,6 @@ }, "length": 1, "pos": 8, - "end": 29 + "end": 30 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTag1.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTag1.json index 1b87d268b9..0dbdd83d2b 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTag1.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTag1.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 29, + "end": 30, "atToken": { "kind": "AtToken", "pos": 8, @@ -34,7 +34,7 @@ "end": 29, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 24, "end": 29, @@ -44,6 +44,6 @@ }, "length": 1, "pos": 8, - "end": 29 + "end": 30 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName1.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName1.json index fe01df5885..1df54fadcd 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName1.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName1.json @@ -34,7 +34,7 @@ "end": 30, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 25, "end": 30, diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName2.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName2.json index f50ce73260..5347b99be7 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName2.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName2.json @@ -34,7 +34,7 @@ "end": 31, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 26, "end": 31, diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType1.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType1.json index 70f2641fd5..204d94779b 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType1.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType1.json @@ -34,7 +34,7 @@ "end": 28 } }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 15, "end": 20, diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType2.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType2.json index 4b720567cc..7c79459768 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType2.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType2.json @@ -34,7 +34,7 @@ "end": 28 } }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 15, "end": 20, diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramWithoutType.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramWithoutType.json index d77e80c751..2ff182483d 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramWithoutType.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramWithoutType.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 18, + "end": 19, "atToken": { "kind": "AtToken", "pos": 8, @@ -24,7 +24,7 @@ "end": 18, "text": "foo" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 15, "end": 18, @@ -34,6 +34,6 @@ }, "length": 1, "pos": 8, - "end": 18 + "end": 19 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTag2.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTag2.json index 16968061af..b51ab3598e 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTag2.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTag2.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 29, + "end": 32, "atToken": { "kind": "AtToken", "pos": 8, @@ -34,7 +34,7 @@ "end": 29, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 24, "end": 29, @@ -45,7 +45,7 @@ "1": { "kind": "JSDocParameterTag", "pos": 34, - "end": 55, + "end": 56, "atToken": { "kind": "AtToken", "pos": 34, @@ -73,7 +73,7 @@ "end": 55, "text": "name2" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 50, "end": 55, @@ -83,6 +83,6 @@ }, "length": 2, "pos": 8, - "end": 55 + "end": 56 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTagOnSameLine.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTagOnSameLine.json index 8818c3a909..3c20d5edcb 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTagOnSameLine.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTagOnSameLine.json @@ -6,7 +6,7 @@ "0": { "kind": "JSDocParameterTag", "pos": 8, - "end": 29, + "end": 30, "atToken": { "kind": "AtToken", "pos": 8, @@ -34,7 +34,7 @@ "end": 29, "text": "name1" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 24, "end": 29, @@ -45,7 +45,7 @@ "1": { "kind": "JSDocParameterTag", "pos": 30, - "end": 51, + "end": 52, "atToken": { "kind": "AtToken", "pos": 30, @@ -73,7 +73,7 @@ "end": 51, "text": "name2" }, - "parameterName": { + "name": { "kind": "Identifier", "pos": 46, "end": 51, @@ -83,6 +83,6 @@ }, "length": 2, "pos": 8, - "end": 51 + "end": 52 } } \ No newline at end of file diff --git a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.typedefTagWithChildrenTags.json b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.typedefTagWithChildrenTags.json index 7ef64f5a97..7a8f9c4bcc 100644 --- a/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.typedefTagWithChildrenTags.json +++ b/tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.typedefTagWithChildrenTags.json @@ -82,12 +82,6 @@ "end": 56, "text": "property" }, - "name": { - "kind": "Identifier", - "pos": 66, - "end": 69, - "text": "age" - }, "typeExpression": { "kind": "JSDocTypeExpression", "pos": 57, @@ -97,6 +91,18 @@ "pos": 58, "end": 64 } + }, + "postParameterName": { + "kind": "Identifier", + "pos": 66, + "end": 69, + "text": "age" + }, + "name": { + "kind": "Identifier", + "pos": 66, + "end": 69, + "text": "age" } }, { @@ -114,12 +120,6 @@ "end": 83, "text": "property" }, - "name": { - "kind": "Identifier", - "pos": 93, - "end": 97, - "text": "name" - }, "typeExpression": { "kind": "JSDocTypeExpression", "pos": 84, @@ -129,6 +129,18 @@ "pos": 85, "end": 91 } + }, + "postParameterName": { + "kind": "Identifier", + "pos": 93, + "end": 97, + "text": "name" + }, + "name": { + "kind": "Identifier", + "pos": 93, + "end": 97, + "text": "name" } } ] diff --git a/tests/baselines/reference/checkJsdocTypedefInParamTag1.js b/tests/baselines/reference/checkJsdocTypedefInParamTag1.js index cc2e302ffc..d50f126c54 100644 --- a/tests/baselines/reference/checkJsdocTypedefInParamTag1.js +++ b/tests/baselines/reference/checkJsdocTypedefInParamTag1.js @@ -15,6 +15,19 @@ function foo(opts) { foo({x: 'abc'}); +/** + * @typedef {Object} AnotherOpts + * @property anotherX {string} + * @property anotherY {string=} + * + * @param {AnotherOpts} opts + */ +function foo1(opts) { + opts.anotherX; +} + +foo1({anotherX: "world"}); + /** * @typedef {object} Opts1 * @property {string} x @@ -24,10 +37,10 @@ foo({x: 'abc'}); * * @param {Opts1} opts */ -function foo1(opts) { +function foo2(opts) { opts.x; } -foo1({x: 'abc'}); +foo2({x: 'abc'}); //// [0.js] @@ -45,6 +58,17 @@ function foo(opts) { opts.x; } foo({ x: 'abc' }); +/** + * @typedef {Object} AnotherOpts + * @property anotherX {string} + * @property anotherY {string=} + * + * @param {AnotherOpts} opts + */ +function foo1(opts) { + opts.anotherX; +} +foo1({ anotherX: "world" }); /** * @typedef {object} Opts1 * @property {string} x @@ -54,7 +78,7 @@ foo({ x: 'abc' }); * * @param {Opts1} opts */ -function foo1(opts) { +function foo2(opts) { opts.x; } -foo1({ x: 'abc' }); +foo2({ x: 'abc' }); diff --git a/tests/baselines/reference/checkJsdocTypedefInParamTag1.symbols b/tests/baselines/reference/checkJsdocTypedefInParamTag1.symbols index 844c4c045a..e6f98a76fa 100644 --- a/tests/baselines/reference/checkJsdocTypedefInParamTag1.symbols +++ b/tests/baselines/reference/checkJsdocTypedefInParamTag1.symbols @@ -23,6 +23,27 @@ foo({x: 'abc'}); >foo : Symbol(foo, Decl(0.js, 0, 0)) >x : Symbol(x, Decl(0.js, 14, 5)) +/** + * @typedef {Object} AnotherOpts + * @property anotherX {string} + * @property anotherY {string=} + * + * @param {AnotherOpts} opts + */ +function foo1(opts) { +>foo1 : Symbol(foo1, Decl(0.js, 14, 16)) +>opts : Symbol(opts, Decl(0.js, 23, 14)) + + opts.anotherX; +>opts.anotherX : Symbol(anotherX, Decl(0.js, 18, 3)) +>opts : Symbol(opts, Decl(0.js, 23, 14)) +>anotherX : Symbol(anotherX, Decl(0.js, 18, 3)) +} + +foo1({anotherX: "world"}); +>foo1 : Symbol(foo1, Decl(0.js, 14, 16)) +>anotherX : Symbol(anotherX, Decl(0.js, 27, 6)) + /** * @typedef {object} Opts1 * @property {string} x @@ -32,16 +53,16 @@ foo({x: 'abc'}); * * @param {Opts1} opts */ -function foo1(opts) { ->foo1 : Symbol(foo1, Decl(0.js, 14, 16)) ->opts : Symbol(opts, Decl(0.js, 25, 14)) +function foo2(opts) { +>foo2 : Symbol(foo2, Decl(0.js, 27, 26)) +>opts : Symbol(opts, Decl(0.js, 38, 14)) opts.x; ->opts.x : Symbol(x, Decl(0.js, 18, 3)) ->opts : Symbol(opts, Decl(0.js, 25, 14)) ->x : Symbol(x, Decl(0.js, 18, 3)) +>opts.x : Symbol(x, Decl(0.js, 31, 3)) +>opts : Symbol(opts, Decl(0.js, 38, 14)) +>x : Symbol(x, Decl(0.js, 31, 3)) } -foo1({x: 'abc'}); ->foo1 : Symbol(foo1, Decl(0.js, 14, 16)) ->x : Symbol(x, Decl(0.js, 28, 6)) +foo2({x: 'abc'}); +>foo2 : Symbol(foo2, Decl(0.js, 27, 26)) +>x : Symbol(x, Decl(0.js, 41, 6)) diff --git a/tests/baselines/reference/checkJsdocTypedefInParamTag1.types b/tests/baselines/reference/checkJsdocTypedefInParamTag1.types index cb21ea2ef0..b0847a7152 100644 --- a/tests/baselines/reference/checkJsdocTypedefInParamTag1.types +++ b/tests/baselines/reference/checkJsdocTypedefInParamTag1.types @@ -26,6 +26,30 @@ foo({x: 'abc'}); >x : string >'abc' : "abc" +/** + * @typedef {Object} AnotherOpts + * @property anotherX {string} + * @property anotherY {string=} + * + * @param {AnotherOpts} opts + */ +function foo1(opts) { +>foo1 : (opts: { anotherX: string; anotherY?: string; }) => void +>opts : { anotherX: string; anotherY?: string; } + + opts.anotherX; +>opts.anotherX : string +>opts : { anotherX: string; anotherY?: string; } +>anotherX : string +} + +foo1({anotherX: "world"}); +>foo1({anotherX: "world"}) : void +>foo1 : (opts: { anotherX: string; anotherY?: string; }) => void +>{anotherX: "world"} : { anotherX: string; } +>anotherX : string +>"world" : "world" + /** * @typedef {object} Opts1 * @property {string} x @@ -35,8 +59,8 @@ foo({x: 'abc'}); * * @param {Opts1} opts */ -function foo1(opts) { ->foo1 : (opts: { x: string; y?: string; z?: string; w?: string; }) => void +function foo2(opts) { +>foo2 : (opts: { x: string; y?: string; z?: string; w?: string; }) => void >opts : { x: string; y?: string; z?: string; w?: string; } opts.x; @@ -44,9 +68,9 @@ function foo1(opts) { >opts : { x: string; y?: string; z?: string; w?: string; } >x : string } -foo1({x: 'abc'}); ->foo1({x: 'abc'}) : void ->foo1 : (opts: { x: string; y?: string; z?: string; w?: string; }) => void +foo2({x: 'abc'}); +>foo2({x: 'abc'}) : void +>foo2 : (opts: { x: string; y?: string; z?: string; w?: string; }) => void >{x: 'abc'} : { x: string; } >x : string >'abc' : "abc" diff --git a/tests/cases/conformance/jsdoc/checkJsdocTypedefInParamTag1.ts b/tests/cases/conformance/jsdoc/checkJsdocTypedefInParamTag1.ts index fa885b9f31..89f609be20 100644 --- a/tests/cases/conformance/jsdoc/checkJsdocTypedefInParamTag1.ts +++ b/tests/cases/conformance/jsdoc/checkJsdocTypedefInParamTag1.ts @@ -18,6 +18,19 @@ function foo(opts) { foo({x: 'abc'}); +/** + * @typedef {Object} AnotherOpts + * @property anotherX {string} + * @property anotherY {string=} + * + * @param {AnotherOpts} opts + */ +function foo1(opts) { + opts.anotherX; +} + +foo1({anotherX: "world"}); + /** * @typedef {object} Opts1 * @property {string} x @@ -27,7 +40,7 @@ foo({x: 'abc'}); * * @param {Opts1} opts */ -function foo1(opts) { +function foo2(opts) { opts.x; } -foo1({x: 'abc'}); +foo2({x: 'abc'});