Skip to content

Commit 1421fe1

Browse files
a-tarasyuka-tarasyuk
committed
feat(17227): add abstract JSDoc tag
1 parent dfe2342 commit 1421fe1

29 files changed

+691
-73
lines changed

‎src/compiler/checker.ts

+45-19
Original file line numberDiff line numberDiff line change
@@ -6800,6 +6800,7 @@ namespace ts {
68006800
...!length(baseTypes) ? [] : [factory.createHeritageClause(SyntaxKind.ExtendsKeyword, map(baseTypes, b => serializeBaseType(b, staticBaseType, localName)))],
68016801
...!length(implementsExpressions) ? [] : [factory.createHeritageClause(SyntaxKind.ImplementsKeyword, implementsExpressions)]
68026802
];
6803+
const modifiers = originalDecl && hasEffectiveModifier(originalDecl, ModifierFlags.Abstract) ? factory.createModifiersFromModifierFlags(ModifierFlags.Abstract) : undefined;
68036804
const symbolProps = getNonInterhitedProperties(classType, baseTypes, getPropertiesOfType(classType));
68046805
const publicSymbolProps = filter(symbolProps, s => {
68056806
// `valueDeclaration` could be undefined if inherited from
@@ -6846,7 +6847,7 @@ namespace ts {
68466847
context.enclosingDeclaration = oldEnclosing;
68476848
addResult(setTextRange(factory.createClassDeclaration(
68486849
/*decorators*/ undefined,
6849-
/*modifiers*/ undefined,
6850+
modifiers,
68506851
localName,
68516852
typeParamDecls,
68526853
heritageClauses,
@@ -7188,20 +7189,11 @@ namespace ts {
71887189
initializer: Expression | undefined
71897190
) => T, methodKind: SignatureDeclaration["kind"], useAccessors: boolean): (p: Symbol, isStatic: boolean, baseType: Type | undefined) => (T | AccessorDeclaration | (T | AccessorDeclaration)[]) {
71907191
return function serializePropertySymbol(p: Symbol, isStatic: boolean, baseType: Type | undefined): (T | AccessorDeclaration | (T | AccessorDeclaration)[]) {
7191-
const modifierFlags = getDeclarationModifierFlagsFromSymbol(p);
7192-
const isPrivate = !!(modifierFlags & ModifierFlags.Private);
7193-
if (isStatic && (p.flags & (SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Alias))) {
7194-
// Only value-only-meaning symbols can be correctly encoded as class statics, type/namespace/alias meaning symbols
7195-
// need to be merged namespace members
7196-
return [];
7197-
}
7198-
if (p.flags & SymbolFlags.Prototype ||
7199-
(baseType && getPropertyOfType(baseType, p.escapedName)
7200-
&& isReadonlySymbol(getPropertyOfType(baseType, p.escapedName)!) === isReadonlySymbol(p)
7201-
&& (p.flags & SymbolFlags.Optional) === (getPropertyOfType(baseType, p.escapedName)!.flags & SymbolFlags.Optional)
7202-
&& isTypeIdenticalTo(getTypeOfSymbol(p), getTypeOfPropertyOfType(baseType, p.escapedName)!))) {
7192+
if (isOmittedSerializationProperty(p, isStatic, baseType)) {
72037193
return [];
72047194
}
7195+
const modifierFlags = getDeclarationModifierFlagsFromSymbol(p);
7196+
const isPrivate = !!(modifierFlags & ModifierFlags.Private);
72057197
const flag = (modifierFlags & ~ModifierFlags.Async) | (isStatic ? ModifierFlags.Static : 0);
72067198
const name = getPropertyNameNodeForSymbol(p, context);
72077199
const firstPropertyLikeDecl = find(p.declarations, or(isPropertyDeclaration, isAccessor, isVariableDeclaration, isPropertySignature, isBinaryExpression, isPropertyAccessExpression));
@@ -7286,6 +7278,29 @@ namespace ts {
72867278
};
72877279
}
72887280

7281+
function isOmittedSerializationProperty(prop: Symbol, isStatic: boolean, type: Type | undefined) {
7282+
// Only value-only-meaning symbols can be correctly encoded as class statics, type/namespace/alias meaning symbols
7283+
// need to be merged namespace members
7284+
if (isStatic && (prop.flags & (SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Alias)) || (prop.flags & SymbolFlags.Prototype)) {
7285+
return true;
7286+
}
7287+
if (type) {
7288+
const baseProp = getPropertyOfType(type, prop.escapedName);
7289+
const basePropType = getTypeOfPropertyOfType(type, prop.escapedName);
7290+
if (baseProp && basePropType) {
7291+
if (getDeclarationModifierFlagsFromSymbol(baseProp) & ModifierFlags.Abstract) {
7292+
return prop === baseProp;
7293+
}
7294+
return (
7295+
(prop.flags & SymbolFlags.Optional) === (baseProp.flags & SymbolFlags.Optional) &&
7296+
isReadonlySymbol(baseProp) === isReadonlySymbol(prop) &&
7297+
isTypeIdenticalTo(getTypeOfSymbol(prop), basePropType)
7298+
);
7299+
}
7300+
}
7301+
return false;
7302+
}
7303+
72897304
function serializePropertySymbolForInterface(p: Symbol, baseType: Type | undefined) {
72907305
return serializePropertySymbolForInterfaceWorker(p, /*isStatic*/ false, baseType);
72917306
}
@@ -28036,7 +28051,7 @@ namespace ts {
2803628051
// In the case of a merged class-module or class-interface declaration,
2803728052
// only the class declaration node will have the Abstract flag set.
2803828053
const valueDecl = expressionType.symbol && getClassLikeDeclarationOfSymbol(expressionType.symbol);
28039-
if (valueDecl && hasSyntacticModifier(valueDecl, ModifierFlags.Abstract)) {
28054+
if (valueDecl && hasEffectiveModifier(valueDecl, ModifierFlags.Abstract)) {
2804028055
error(node, Diagnostics.Cannot_create_an_instance_of_an_abstract_class);
2804128056
return resolveErrorCall(node);
2804228057
}
@@ -29531,7 +29546,7 @@ namespace ts {
2953129546
if (type && type.flags & TypeFlags.Never) {
2953229547
error(getEffectiveReturnTypeNode(func), Diagnostics.A_function_returning_never_cannot_have_a_reachable_end_point);
2953329548
}
29534-
else if (type && !hasExplicitReturn) {
29549+
else if (type && !hasExplicitReturn && !hasEffectiveModifier(func, ModifierFlags.Abstract)) {
2953529550
// minimal check: function has syntactic return type annotation and no explicit return statements in the body
2953629551
// this function does not conform to the specification.
2953729552
// NOTE: having returnType !== undefined is a precondition for entering this branch so func.type will always be present
@@ -31899,7 +31914,7 @@ namespace ts {
3189931914

3190031915
// Abstract methods cannot have an implementation.
3190131916
// Extra checks are to avoid reporting multiple errors relating to the "abstractness" of the node.
31902-
if (hasSyntacticModifier(node, ModifierFlags.Abstract) && node.kind === SyntaxKind.MethodDeclaration && node.body) {
31917+
if (hasEffectiveModifier(node, ModifierFlags.Abstract) && node.kind === SyntaxKind.MethodDeclaration && node.body && !isInJSFile(node)) {
3190331918
error(node, Diagnostics.Method_0_cannot_have_an_implementation_because_it_is_marked_abstract, declarationNameToString(node.name));
3190431919
}
3190531920
}
@@ -31996,7 +32011,7 @@ namespace ts {
3199632011
checkSignatureDeclaration(node);
3199732012
if (node.kind === SyntaxKind.GetAccessor) {
3199832013
if (!(node.flags & NodeFlags.Ambient) && nodeIsPresent(node.body) && (node.flags & NodeFlags.HasImplicitReturn)) {
31999-
if (!(node.flags & NodeFlags.HasExplicitReturn)) {
32014+
if (!(node.flags & NodeFlags.HasExplicitReturn) && !(isInJSFile(node) && hasEffectiveModifier(node, ModifierFlags.Abstract))) {
3200032015
error(node.name, Diagnostics.A_get_accessor_must_return_a_value);
3200132016
}
3200232017
}
@@ -33277,6 +33292,15 @@ namespace ts {
3327733292
checkSignatureDeclaration(node);
3327833293
}
3327933294

33295+
function checkJSDocAbstractTag(node: JSDocAbstractTag): void {
33296+
const host = getEffectiveJSDocHost(node);
33297+
if (host && isClassElement(host)) {
33298+
if (!hasEffectiveModifier(host.parent, ModifierFlags.Abstract)) {
33299+
error(host, Diagnostics.Abstract_methods_can_only_appear_within_an_abstract_class);
33300+
}
33301+
}
33302+
}
33303+
3328033304
function checkJSDocImplementsTag(node: JSDocImplementsTag): void {
3328133305
const classLike = getEffectiveJSDocHost(node);
3328233306
if (!classLike || !isClassDeclaration(classLike) && !isClassExpression(classLike)) {
@@ -35896,7 +35920,7 @@ namespace ts {
3589635920
const properties = getPropertiesOfType(getTypeWithThisArgument(base, type.thisType));
3589735921
for (const prop of properties) {
3589835922
const existing = seen.get(prop.escapedName);
35899-
if (existing && !isPropertyIdenticalTo(existing, prop)) {
35923+
if (existing && !isPropertyIdenticalTo(existing, prop) && !(getDeclarationModifierFlagsFromSymbol(prop) & ModifierFlags.Abstract)) {
3590035924
seen.delete(prop.escapedName);
3590135925
}
3590235926
}
@@ -36969,6 +36993,8 @@ namespace ts {
3696936993
return checkImportType(<ImportTypeNode>node);
3697036994
case SyntaxKind.NamedTupleMember:
3697136995
return checkNamedTupleMember(<NamedTupleMember>node);
36996+
case SyntaxKind.JSDocAbstractTag:
36997+
return checkJSDocAbstractTag(<JSDocAbstractTag>node);
3697236998
case SyntaxKind.JSDocAugmentsTag:
3697336999
return checkJSDocAugmentsTag(node as JSDocAugmentsTag);
3697437000
case SyntaxKind.JSDocImplementsTag:
@@ -39851,7 +39877,7 @@ namespace ts {
3985139877
return grammarErrorAtPos(accessor, accessor.end - 1, ";".length, Diagnostics._0_expected, "{");
3985239878
}
3985339879
}
39854-
if (accessor.body && hasSyntacticModifier(accessor, ModifierFlags.Abstract)) {
39880+
if (accessor.body && hasEffectiveModifier(accessor, ModifierFlags.Abstract) && !isInJSFile(accessor)) {
3985539881
return grammarErrorOnNode(accessor, Diagnostics.An_abstract_accessor_cannot_have_an_implementation);
3985639882
}
3985739883
if (accessor.typeParameters) {

‎src/compiler/factory/nodeFactory.ts

+3
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,8 @@ namespace ts {
354354
get updateJSDocThisTag() { return getJSDocTypeLikeTagUpdateFunction<JSDocThisTag>(SyntaxKind.JSDocThisTag); },
355355
get createJSDocEnumTag() { return getJSDocTypeLikeTagCreateFunction<JSDocEnumTag>(SyntaxKind.JSDocEnumTag); },
356356
get updateJSDocEnumTag() { return getJSDocTypeLikeTagUpdateFunction<JSDocEnumTag>(SyntaxKind.JSDocEnumTag); },
357+
get createJSDocAbstractTag() { return getJSDocSimpleTagCreateFunction<JSDocAbstractTag>(SyntaxKind.JSDocAbstractTag); },
358+
get updateJSDocAbstractTag() { return getJSDocSimpleTagUpdateFunction<JSDocAbstractTag>(SyntaxKind.JSDocAbstractTag); },
357359
get createJSDocAuthorTag() { return getJSDocSimpleTagCreateFunction<JSDocAuthorTag>(SyntaxKind.JSDocAuthorTag); },
358360
get updateJSDocAuthorTag() { return getJSDocSimpleTagUpdateFunction<JSDocAuthorTag>(SyntaxKind.JSDocAuthorTag); },
359361
get createJSDocClassTag() { return getJSDocSimpleTagCreateFunction<JSDocClassTag>(SyntaxKind.JSDocClassTag); },
@@ -5859,6 +5861,7 @@ namespace ts {
58595861
case SyntaxKind.JSDocReturnTag: return "returns";
58605862
case SyntaxKind.JSDocThisTag: return "this";
58615863
case SyntaxKind.JSDocEnumTag: return "enum";
5864+
case SyntaxKind.JSDocAbstractTag: return "abstract";
58625865
case SyntaxKind.JSDocAuthorTag: return "author";
58635866
case SyntaxKind.JSDocClassTag: return "class";
58645867
case SyntaxKind.JSDocPublicTag: return "public";

‎src/compiler/factory/nodeTests.ts

+4
Original file line numberDiff line numberDiff line change
@@ -757,6 +757,10 @@ namespace ts {
757757
return node.kind === SyntaxKind.JSDocAugmentsTag;
758758
}
759759

760+
export function isJSDocAbstractTag(node: Node): node is JSDocAbstractTag {
761+
return node.kind === SyntaxKind.JSDocAbstractTag;
762+
}
763+
760764
export function isJSDocAuthorTag(node: Node): node is JSDocAuthorTag {
761765
return node.kind === SyntaxKind.JSDocAuthorTag;
762766
}

‎src/compiler/parser.ts

+4
Original file line numberDiff line numberDiff line change
@@ -532,6 +532,7 @@ namespace ts {
532532
case SyntaxKind.JSDocTypeLiteral:
533533
return forEach((node as JSDocTypeLiteral).jsDocPropertyTags, cbNode);
534534
case SyntaxKind.JSDocTag:
535+
case SyntaxKind.JSDocAbstractTag:
535536
case SyntaxKind.JSDocClassTag:
536537
case SyntaxKind.JSDocPublicTag:
537538
case SyntaxKind.JSDocPrivateTag:
@@ -7443,6 +7444,9 @@ namespace ts {
74437444

74447445
let tag: JSDocTag | undefined;
74457446
switch (tagName.escapedText) {
7447+
case "abstract":
7448+
tag = parseSimpleTag(start, factory.createJSDocAbstractTag, tagName, margin, indentText);
7449+
break;
74467450
case "author":
74477451
tag = parseAuthorTag(start, tagName, margin, indentText);
74487452
break;

‎src/compiler/types.ts

+7
Original file line numberDiff line numberDiff line change
@@ -378,6 +378,7 @@ namespace ts {
378378
JSDocTag,
379379
JSDocAugmentsTag,
380380
JSDocImplementsTag,
381+
JSDocAbstractTag,
381382
JSDocAuthorTag,
382383
JSDocDeprecatedTag,
383384
JSDocClassTag,
@@ -3166,6 +3167,10 @@ namespace ts {
31663167
readonly class: ExpressionWithTypeArguments & { readonly expression: Identifier | PropertyAccessEntityNameExpression };
31673168
}
31683169

3170+
export interface JSDocAbstractTag extends JSDocTag {
3171+
readonly kind: SyntaxKind.JSDocAbstractTag;
3172+
}
3173+
31693174
export interface JSDocAuthorTag extends JSDocTag {
31703175
readonly kind: SyntaxKind.JSDocAuthorTag;
31713176
}
@@ -7160,6 +7165,8 @@ namespace ts {
71607165
updateJSDocAugmentsTag(node: JSDocAugmentsTag, tagName: Identifier | undefined, className: JSDocAugmentsTag["class"], comment: string | undefined): JSDocAugmentsTag;
71617166
createJSDocImplementsTag(tagName: Identifier | undefined, className: JSDocImplementsTag["class"], comment?: string): JSDocImplementsTag;
71627167
updateJSDocImplementsTag(node: JSDocImplementsTag, tagName: Identifier | undefined, className: JSDocImplementsTag["class"], comment: string | undefined): JSDocImplementsTag;
7168+
createJSDocAbstractTag(tagName: Identifier | undefined, comment?: string): JSDocAbstractTag;
7169+
updateJSDocAbstractTag(node: JSDocAbstractTag, tagName: Identifier | undefined, comment: string | undefined): JSDocAbstractTag;
71637170
createJSDocAuthorTag(tagName: Identifier | undefined, comment?: string): JSDocAuthorTag;
71647171
updateJSDocAuthorTag(node: JSDocAuthorTag, tagName: Identifier | undefined, comment: string | undefined): JSDocAuthorTag;
71657172
createJSDocClassTag(tagName: Identifier | undefined, comment?: string): JSDocClassTag;

‎src/compiler/utilities.ts

+1
Original file line numberDiff line numberDiff line change
@@ -4719,6 +4719,7 @@ namespace ts {
47194719
if (getJSDocPrivateTagNoCache(node)) flags |= ModifierFlags.Private;
47204720
if (getJSDocProtectedTagNoCache(node)) flags |= ModifierFlags.Protected;
47214721
if (getJSDocReadonlyTagNoCache(node)) flags |= ModifierFlags.Readonly;
4722+
if (getJSDocAbstractTagNoCache(node)) flags |= ModifierFlags.Abstract;
47224723
}
47234724
if (getJSDocDeprecatedTagNoCache(node)) flags |= ModifierFlags.Deprecated;
47244725
}

‎src/compiler/utilitiesPublic.ts

+4
Original file line numberDiff line numberDiff line change
@@ -767,6 +767,10 @@ namespace ts {
767767
return getFirstJSDocTag(node, isJSDocReadonlyTag, /*noCache*/ true);
768768
}
769769

770+
export function getJSDocAbstractTagNoCache(node: Node): JSDocAbstractTag | undefined {
771+
return getFirstJSDocTag(node, isJSDocAbstractTag, /*noCache*/ true);
772+
}
773+
770774
/** Gets the JSDoc deprecated tag for the node if present */
771775
export function getJSDocDeprecatedTag(node: Node): JSDocDeprecatedTag | undefined {
772776
return getFirstJSDocTag(node, isJSDocDeprecatedTag);

0 commit comments

Comments
 (0)