Skip to content

Commit f0bedf7

Browse files
author
Andy Hanson
committed
Fixes to @Augments handling
1 parent b4018a2 commit f0bedf7

25 files changed

+308
-34
lines changed

‎src/compiler/checker.ts‎

Lines changed: 43 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4882,7 +4882,16 @@ namespace ts {
48824882
}
48834883

48844884
function getBaseTypeNodeOfClass(type: InterfaceType): ExpressionWithTypeArguments {
4885-
return getClassExtendsHeritageClauseElement(<ClassLikeDeclaration>type.symbol.valueDeclaration);
4885+
const decl = <ClassLikeDeclaration>type.symbol.valueDeclaration;
4886+
if (isInJavaScriptFile(decl)) {
4887+
// Prefer an @augments tag because it may have type parameters.
4888+
const tag = getJSDocAugmentsTag(decl);
4889+
if (tag) {
4890+
return tag.class;
4891+
}
4892+
}
4893+
4894+
return getClassExtendsHeritageClauseElement(decl);
48864895
}
48874896

48884897
function getConstructorsForTypeArguments(type: Type, typeArgumentNodes: ReadonlyArray<TypeNode>, location: Node): Signature[] {
@@ -4986,15 +4995,6 @@ namespace ts {
49864995
baseType = getReturnTypeOfSignature(constructors[0]);
49874996
}
49884997

4989-
// In a JS file, you can use the @augments jsdoc tag to specify a base type with type parameters
4990-
const valueDecl = type.symbol.valueDeclaration;
4991-
if (valueDecl && isInJavaScriptFile(valueDecl)) {
4992-
const augTag = getJSDocAugmentsTag(type.symbol.valueDeclaration);
4993-
if (augTag && augTag.typeExpression && augTag.typeExpression.type) {
4994-
baseType = getTypeFromTypeNode(augTag.typeExpression.type);
4995-
}
4996-
}
4997-
49984998
if (baseType === unknownType) {
49994999
return;
50005000
}
@@ -5003,7 +5003,7 @@ namespace ts {
50035003
return;
50045004
}
50055005
if (type === baseType || hasBaseType(baseType, type)) {
5006-
error(valueDecl, Diagnostics.Type_0_recursively_references_itself_as_a_base_type,
5006+
error(type.symbol.valueDeclaration, Diagnostics.Type_0_recursively_references_itself_as_a_base_type,
50075007
typeToString(type, /*enclosingDeclaration*/ undefined, TypeFormatFlags.WriteArrayAsGenericType));
50085008
return;
50095009
}
@@ -19788,6 +19788,36 @@ namespace ts {
1978819788
}
1978919789
}
1979019790

19791+
function checkJSDocAugmentsTag(node: JSDocAugmentsTag): void {
19792+
const cls = getNodeCommentedByJSDocTag(node);
19793+
if (!isClassDeclaration(cls) && !isClassExpression(cls)) {
19794+
error(cls, Diagnostics.JSDoc_augments_tag_will_be_ignored_if_not_attached_to_a_class_declaration);
19795+
return;
19796+
}
19797+
19798+
const name: Identifier = node.class.expression.kind === SyntaxKind.PropertyAccessExpression ? (node.class.expression as PropertyAccessExpression).name : (node.class.expression as Identifier);
19799+
const extend = getClassExtendsHeritageClauseElement(cls);
19800+
if (extend) {
19801+
const className = getClassName(extend.expression);
19802+
if (className && name.escapedText !== className.escapedText) {
19803+
error(name, Diagnostics.JSDoc_augments_tag_declares_to_extend_0_but_actual_class_augments_1,
19804+
unescapeLeadingUnderscores(name.escapedText),
19805+
unescapeLeadingUnderscores(className.escapedText));
19806+
}
19807+
}
19808+
}
19809+
19810+
function getClassName(node: Expression): Identifier | undefined {
19811+
switch (node.kind) {
19812+
case SyntaxKind.Identifier:
19813+
return node as Identifier;
19814+
case SyntaxKind.PropertyAccessExpression:
19815+
return (node as PropertyAccessExpression).name;
19816+
default:
19817+
return undefined;
19818+
}
19819+
}
19820+
1979119821
function checkJSDocComment(node: JSDoc) {
1979219822
if ((node as JSDoc).tags) {
1979319823
for (const tag of (node as JSDoc).tags) {
@@ -22490,6 +22520,8 @@ namespace ts {
2249022520
case SyntaxKind.ParenthesizedType:
2249122521
case SyntaxKind.TypeOperator:
2249222522
return checkSourceElement((<ParenthesizedTypeNode | TypeOperatorNode>node).type);
22523+
case SyntaxKind.JSDocAugmentsTag:
22524+
return checkJSDocAugmentsTag(node as JSDocAugmentsTag);
2249322525
case SyntaxKind.JSDocTypedefTag:
2249422526
return checkJSDocTypedefTag(node as JSDocTypedefTag);
2249522527
case SyntaxKind.JSDocComment:

‎src/compiler/diagnosticMessages.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3511,6 +3511,14 @@
35113511
"category": "Error",
35123512
"code": 8021
35133513
},
3514+
"JSDoc '@augments' tag will be ignored if not attached to a class declaration.": {
3515+
"category": "Error",
3516+
"code": 8022
3517+
},
3518+
"JSDoc '@augments' tag declares to extend '{0}', but actual class augments '{1}'.": {
3519+
"category": "Error",
3520+
"code": 8023
3521+
},
35143522
"Only identifiers/qualified-names with optional type arguments are currently supported in a class 'extends' clause.": {
35153523
"category": "Error",
35163524
"code": 9002

‎src/compiler/parser.ts‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -424,7 +424,7 @@ namespace ts {
424424
case SyntaxKind.JSDocTypeTag:
425425
return visitNode(cbNode, (<JSDocTypeTag>node).typeExpression);
426426
case SyntaxKind.JSDocAugmentsTag:
427-
return visitNode(cbNode, (<JSDocAugmentsTag>node).typeExpression);
427+
return visitNode(cbNode, (<JSDocAugmentsTag>node).class);
428428
case SyntaxKind.JSDocTemplateTag:
429429
return visitNodes(cbNode, cbNodes, (<JSDocTemplateTag>node).typeParameters);
430430
case SyntaxKind.JSDocTypedefTag:
@@ -5624,13 +5624,16 @@ namespace ts {
56245624
function parseExpressionWithTypeArguments(): ExpressionWithTypeArguments {
56255625
const node = <ExpressionWithTypeArguments>createNode(SyntaxKind.ExpressionWithTypeArguments);
56265626
node.expression = parseLeftHandSideExpressionOrHigher();
5627-
if (token() === SyntaxKind.LessThanToken) {
5628-
node.typeArguments = parseBracketedList(ParsingContext.TypeArguments, parseType, SyntaxKind.LessThanToken, SyntaxKind.GreaterThanToken);
5629-
}
5630-
5627+
node.typeArguments = tryParseTypeArguments();
56315628
return finishNode(node);
56325629
}
56335630

5631+
function tryParseTypeArguments(): NodeArray<TypeNode> | undefined {
5632+
return token() === SyntaxKind.LessThanToken
5633+
? parseBracketedList(ParsingContext.TypeArguments, parseType, SyntaxKind.LessThanToken, SyntaxKind.GreaterThanToken)
5634+
: undefined;
5635+
}
5636+
56345637
function isHeritageClause(): boolean {
56355638
return token() === SyntaxKind.ExtendsKeyword || token() === SyntaxKind.ImplementsKeyword;
56365639
}
@@ -6604,15 +6607,36 @@ namespace ts {
66046607
}
66056608

66066609
function parseAugmentsTag(atToken: AtToken, tagName: Identifier): JSDocAugmentsTag {
6607-
const typeExpression = parseJSDocTypeExpression(/*requireBraces*/ true);
6608-
66096610
const result = <JSDocAugmentsTag>createNode(SyntaxKind.JSDocAugmentsTag, atToken.pos);
66106611
result.atToken = atToken;
66116612
result.tagName = tagName;
6612-
result.typeExpression = typeExpression;
6613+
result.class = parseValidExpressionWithTypeArguments();
66136614
return finishNode(result);
66146615
}
66156616

6617+
function parseValidExpressionWithTypeArguments(): ExpressionWithTypeArguments & { expression: Identifier | PropertyAccessEntityNameExpression } {
6618+
const usedBrace = parseOptional(SyntaxKind.OpenBraceToken);
6619+
const node = createNode(SyntaxKind.ExpressionWithTypeArguments) as ExpressionWithTypeArguments & { expression: Identifier | PropertyAccessEntityNameExpression };
6620+
node.expression = parsePropertyAccessEntityNameExpression();
6621+
node.typeArguments = tryParseTypeArguments();
6622+
const res = finishNode(node);
6623+
if (usedBrace) {
6624+
parseExpected(SyntaxKind.CloseBraceToken);
6625+
}
6626+
return res;
6627+
}
6628+
6629+
function parsePropertyAccessEntityNameExpression() {
6630+
let node: Identifier | PropertyAccessEntityNameExpression = parseJSDocIdentifierName(/*createIfMissing*/ true);
6631+
while (token() === SyntaxKind.DotToken) {
6632+
const prop: PropertyAccessEntityNameExpression = createNode(SyntaxKind.PropertyAccessExpression, node.pos) as PropertyAccessEntityNameExpression;
6633+
prop.expression = node;
6634+
prop.name = parseJSDocIdentifierName();
6635+
node = finishNode(prop);
6636+
}
6637+
return node;
6638+
}
6639+
66166640
function parseClassTag(atToken: AtToken, tagName: Identifier): JSDocClassTag {
66176641
const tag = <JSDocClassTag>createNode(SyntaxKind.JSDocClassTag, atToken.pos);
66186642
tag.atToken = atToken;

‎src/compiler/scanner.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1856,6 +1856,12 @@ namespace ts {
18561856
case CharacterCodes.closeBracket:
18571857
pos++;
18581858
return token = SyntaxKind.CloseBracketToken;
1859+
case CharacterCodes.lessThan:
1860+
pos++;
1861+
return token = SyntaxKind.LessThanToken;
1862+
case CharacterCodes.greaterThan:
1863+
pos++;
1864+
return token = SyntaxKind.GreaterThanToken;
18591865
case CharacterCodes.equals:
18601866
pos++;
18611867
return token = SyntaxKind.EqualsToken;

‎src/compiler/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2161,7 +2161,7 @@ namespace ts {
21612161

21622162
export interface JSDocAugmentsTag extends JSDocTag {
21632163
kind: SyntaxKind.JSDocAugmentsTag;
2164-
typeExpression: JSDocTypeExpression;
2164+
class: ExpressionWithTypeArguments & { expression: Identifier | PropertyAccessEntityNameExpression };
21652165
}
21662166

21672167
export interface JSDocClassTag extends JSDocTag {

‎src/compiler/utilities.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1581,8 +1581,7 @@ namespace ts {
15811581
return undefined;
15821582
}
15831583
const name = node.name.escapedText;
1584-
Debug.assert(node.parent!.kind === SyntaxKind.JSDocComment);
1585-
const func = node.parent!.parent!;
1584+
const func = getNodeCommentedByJSDocTag(node);
15861585
if (!isFunctionLike(func)) {
15871586
return undefined;
15881587
}
@@ -1591,6 +1590,11 @@ namespace ts {
15911590
return parameter && parameter.symbol;
15921591
}
15931592

1593+
export function getNodeCommentedByJSDocTag(node: JSDocTag): Node {
1594+
Debug.assert(node.parent!.kind === SyntaxKind.JSDocComment);
1595+
return node.parent!.parent!;
1596+
}
1597+
15941598
export function getTypeParameterFromJsDoc(node: TypeParameterDeclaration & { parent: JSDocTemplateTag }): TypeParameterDeclaration | undefined {
15951599
const name = node.name.escapedText;
15961600
const { typeParameters } = (node.parent.parent.parent as ts.SignatureDeclaration | ts.InterfaceDeclaration | ts.ClassDeclaration);

‎src/services/completions.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -581,11 +581,10 @@ namespace ts.Completions {
581581

582582
return { symbols, isGlobalCompletion, isMemberCompletion, allowStringLiteral, isNewIdentifierLocation, location, isRightOfDot: (isRightOfDot || isRightOfOpenTag), request, keywordFilters };
583583

584-
type JSDocTagWithTypeExpression = JSDocAugmentsTag | JSDocParameterTag | JSDocPropertyTag | JSDocReturnTag | JSDocTypeTag | JSDocTypedefTag;
584+
type JSDocTagWithTypeExpression = JSDocParameterTag | JSDocPropertyTag | JSDocReturnTag | JSDocTypeTag | JSDocTypedefTag;
585585

586586
function isTagWithTypeExpression(tag: JSDocTag): tag is JSDocTagWithTypeExpression {
587587
switch (tag.kind) {
588-
case SyntaxKind.JSDocAugmentsTag:
589588
case SyntaxKind.JSDocParameterTag:
590589
case SyntaxKind.JSDocPropertyTag:
591590
case SyntaxKind.JSDocReturnTag:

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

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
1-
/a.js(2,14): error TS1005: '{' expected.
1+
/a.js(2,14): error TS1003: Identifier expected.
2+
/a.js(2,14): error TS8023: JSDoc '@augments' tag declares to extend '', but actual class augments 'A'.
3+
/a.js(5,14): error TS2339: Property 'x' does not exist on type 'B'.
24

35

4-
==== /a.js (1 errors) ====
6+
==== /a.js (3 errors) ====
57
class A { constructor() { this.x = 0; } }
68
/** @augments */
7-
~
8-
!!! error TS1005: '{' expected.
9+
10+
!!! error TS1003: Identifier expected.
11+
12+
!!! error TS8023: JSDoc '@augments' tag declares to extend '', but actual class augments 'A'.
913
class B extends A {
1014
m() {
1115
this.x
16+
~
17+
!!! error TS2339: Property 'x' does not exist on type 'B'.
1218
}
1319
}
1420

‎tests/baselines/reference/jsdocAugmentsMissingType.symbols‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,7 @@ class B extends A {
1414
>m : Symbol(B.m, Decl(a.js, 2, 19))
1515

1616
this.x
17-
>this.x : Symbol(A.x, Decl(a.js, 0, 25))
1817
>this : Symbol(B, Decl(a.js, 0, 41))
19-
>x : Symbol(A.x, Decl(a.js, 0, 25))
2018
}
2119
}
2220

‎tests/baselines/reference/jsdocAugmentsMissingType.types‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ class A { constructor() { this.x = 0; } }
1010
/** @augments */
1111
class B extends A {
1212
>B : B
13-
>A : A
13+
>A : typeof A
1414

1515
m() {
1616
>m : () => void
1717

1818
this.x
19-
>this.x : number
19+
>this.x : any
2020
>this : this
21-
>x : number
21+
>x : any
2222
}
2323
}
2424

0 commit comments

Comments
 (0)