Skip to content

Commit

Permalink
feat(17227): add abstract JSDoc tag
Browse files Browse the repository at this point in the history
  • Loading branch information
@a-tarasyuk
a-tarasyuk committed Jan 10, 2021
1 parent dfe2342 commit 1421fe1
Show file tree
Hide file tree
Showing 29 changed files with 691 additions and 73 deletions.
64 changes: 45 additions & 19 deletions src/compiler/checker.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6800,6 +6800,7 @@ namespace ts {
...!length(baseTypes) ? [] : [factory.createHeritageClause(SyntaxKind.ExtendsKeyword, map(baseTypes, b => serializeBaseType(b, staticBaseType, localName)))],
...!length(implementsExpressions) ? [] : [factory.createHeritageClause(SyntaxKind.ImplementsKeyword, implementsExpressions)]
];
const modifiers = originalDecl && hasEffectiveModifier(originalDecl, ModifierFlags.Abstract) ? factory.createModifiersFromModifierFlags(ModifierFlags.Abstract) : undefined;
const symbolProps = getNonInterhitedProperties(classType, baseTypes, getPropertiesOfType(classType));
const publicSymbolProps = filter(symbolProps, s => {
// `valueDeclaration` could be undefined if inherited from
Expand Down Expand Up @@ -6846,7 +6847,7 @@ namespace ts {
context.enclosingDeclaration = oldEnclosing;
addResult(setTextRange(factory.createClassDeclaration(
/*decorators*/ undefined,
/*modifiers*/ undefined,
modifiers,
localName,
typeParamDecls,
heritageClauses,
Expand Down Expand Up @@ -7188,20 +7189,11 @@ namespace ts {
initializer: Expression | undefined
) => T, methodKind: SignatureDeclaration["kind"], useAccessors: boolean): (p: Symbol, isStatic: boolean, baseType: Type | undefined) => (T | AccessorDeclaration | (T | AccessorDeclaration)[]) {
return function serializePropertySymbol(p: Symbol, isStatic: boolean, baseType: Type | undefined): (T | AccessorDeclaration | (T | AccessorDeclaration)[]) {
const modifierFlags = getDeclarationModifierFlagsFromSymbol(p);
const isPrivate = !!(modifierFlags & ModifierFlags.Private);
if (isStatic && (p.flags & (SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Alias))) {
// Only value-only-meaning symbols can be correctly encoded as class statics, type/namespace/alias meaning symbols
// need to be merged namespace members
return [];
}
if (p.flags & SymbolFlags.Prototype ||
(baseType && getPropertyOfType(baseType, p.escapedName)
&& isReadonlySymbol(getPropertyOfType(baseType, p.escapedName)!) === isReadonlySymbol(p)
&& (p.flags & SymbolFlags.Optional) === (getPropertyOfType(baseType, p.escapedName)!.flags & SymbolFlags.Optional)
&& isTypeIdenticalTo(getTypeOfSymbol(p), getTypeOfPropertyOfType(baseType, p.escapedName)!))) {
if (isOmittedSerializationProperty(p, isStatic, baseType)) {
return [];
}
const modifierFlags = getDeclarationModifierFlagsFromSymbol(p);
const isPrivate = !!(modifierFlags & ModifierFlags.Private);
const flag = (modifierFlags & ~ModifierFlags.Async) | (isStatic ? ModifierFlags.Static : 0);
const name = getPropertyNameNodeForSymbol(p, context);
const firstPropertyLikeDecl = find(p.declarations, or(isPropertyDeclaration, isAccessor, isVariableDeclaration, isPropertySignature, isBinaryExpression, isPropertyAccessExpression));
Expand Down Expand Up @@ -7286,6 +7278,29 @@ namespace ts {
};
}

function isOmittedSerializationProperty(prop: Symbol, isStatic: boolean, type: Type | undefined) {
// Only value-only-meaning symbols can be correctly encoded as class statics, type/namespace/alias meaning symbols
// need to be merged namespace members
if (isStatic && (prop.flags & (SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Alias)) || (prop.flags & SymbolFlags.Prototype)) {
return true;
}
if (type) {
const baseProp = getPropertyOfType(type, prop.escapedName);
const basePropType = getTypeOfPropertyOfType(type, prop.escapedName);
if (baseProp && basePropType) {
if (getDeclarationModifierFlagsFromSymbol(baseProp) & ModifierFlags.Abstract) {
return prop === baseProp;
}
return (
(prop.flags & SymbolFlags.Optional) === (baseProp.flags & SymbolFlags.Optional) &&
isReadonlySymbol(baseProp) === isReadonlySymbol(prop) &&
isTypeIdenticalTo(getTypeOfSymbol(prop), basePropType)
);
}
}
return false;
}

function serializePropertySymbolForInterface(p: Symbol, baseType: Type | undefined) {
return serializePropertySymbolForInterfaceWorker(p, /*isStatic*/ false, baseType);
}
Expand Down Expand Up @@ -28036,7 +28051,7 @@ namespace ts {
// In the case of a merged class-module or class-interface declaration,
// only the class declaration node will have the Abstract flag set.
const valueDecl = expressionType.symbol && getClassLikeDeclarationOfSymbol(expressionType.symbol);
if (valueDecl && hasSyntacticModifier(valueDecl, ModifierFlags.Abstract)) {
if (valueDecl && hasEffectiveModifier(valueDecl, ModifierFlags.Abstract)) {
error(node, Diagnostics.Cannot_create_an_instance_of_an_abstract_class);
return resolveErrorCall(node);
}
Expand Down Expand Up @@ -29531,7 +29546,7 @@ namespace ts {
if (type && type.flags & TypeFlags.Never) {
error(getEffectiveReturnTypeNode(func), Diagnostics.A_function_returning_never_cannot_have_a_reachable_end_point);
}
else if (type && !hasExplicitReturn) {
else if (type && !hasExplicitReturn && !hasEffectiveModifier(func, ModifierFlags.Abstract)) {
// minimal check: function has syntactic return type annotation and no explicit return statements in the body
// this function does not conform to the specification.
// NOTE: having returnType !== undefined is a precondition for entering this branch so func.type will always be present
Expand Down Expand Up @@ -31899,7 +31914,7 @@ namespace ts {

// Abstract methods cannot have an implementation.
// Extra checks are to avoid reporting multiple errors relating to the "abstractness" of the node.
if (hasSyntacticModifier(node, ModifierFlags.Abstract) && node.kind === SyntaxKind.MethodDeclaration && node.body) {
if (hasEffectiveModifier(node, ModifierFlags.Abstract) && node.kind === SyntaxKind.MethodDeclaration && node.body && !isInJSFile(node)) {
error(node, Diagnostics.Method_0_cannot_have_an_implementation_because_it_is_marked_abstract, declarationNameToString(node.name));
}
}
Expand Down Expand Up @@ -31996,7 +32011,7 @@ namespace ts {
checkSignatureDeclaration(node);
if (node.kind === SyntaxKind.GetAccessor) {
if (!(node.flags & NodeFlags.Ambient) && nodeIsPresent(node.body) && (node.flags & NodeFlags.HasImplicitReturn)) {
if (!(node.flags & NodeFlags.HasExplicitReturn)) {
if (!(node.flags & NodeFlags.HasExplicitReturn) && !(isInJSFile(node) && hasEffectiveModifier(node, ModifierFlags.Abstract))) {
error(node.name, Diagnostics.A_get_accessor_must_return_a_value);
}
}
Expand Down Expand Up @@ -33277,6 +33292,15 @@ namespace ts {
checkSignatureDeclaration(node);
}

function checkJSDocAbstractTag(node: JSDocAbstractTag): void {
const host = getEffectiveJSDocHost(node);
if (host && isClassElement(host)) {
if (!hasEffectiveModifier(host.parent, ModifierFlags.Abstract)) {
error(host, Diagnostics.Abstract_methods_can_only_appear_within_an_abstract_class);
}
}
}

function checkJSDocImplementsTag(node: JSDocImplementsTag): void {
const classLike = getEffectiveJSDocHost(node);
if (!classLike || !isClassDeclaration(classLike) && !isClassExpression(classLike)) {
Expand Down Expand Up @@ -35896,7 +35920,7 @@ namespace ts {
const properties = getPropertiesOfType(getTypeWithThisArgument(base, type.thisType));
for (const prop of properties) {
const existing = seen.get(prop.escapedName);
if (existing && !isPropertyIdenticalTo(existing, prop)) {
if (existing && !isPropertyIdenticalTo(existing, prop) && !(getDeclarationModifierFlagsFromSymbol(prop) & ModifierFlags.Abstract)) {
seen.delete(prop.escapedName);
}
}
Expand Down Expand Up @@ -36969,6 +36993,8 @@ namespace ts {
return checkImportType(<ImportTypeNode>node);
case SyntaxKind.NamedTupleMember:
return checkNamedTupleMember(<NamedTupleMember>node);
case SyntaxKind.JSDocAbstractTag:
return checkJSDocAbstractTag(<JSDocAbstractTag>node);
case SyntaxKind.JSDocAugmentsTag:
return checkJSDocAugmentsTag(node as JSDocAugmentsTag);
case SyntaxKind.JSDocImplementsTag:
Expand Down Expand Up @@ -39851,7 +39877,7 @@ namespace ts {
return grammarErrorAtPos(accessor, accessor.end - 1, ";".length, Diagnostics._0_expected, "{");
}
}
if (accessor.body && hasSyntacticModifier(accessor, ModifierFlags.Abstract)) {
if (accessor.body && hasEffectiveModifier(accessor, ModifierFlags.Abstract) && !isInJSFile(accessor)) {
return grammarErrorOnNode(accessor, Diagnostics.An_abstract_accessor_cannot_have_an_implementation);
}
if (accessor.typeParameters) {
Expand Down
3 changes: 3 additions & 0 deletions src/compiler/factory/nodeFactory.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,8 @@ namespace ts {
get updateJSDocThisTag() { return getJSDocTypeLikeTagUpdateFunction<JSDocThisTag>(SyntaxKind.JSDocThisTag); },
get createJSDocEnumTag() { return getJSDocTypeLikeTagCreateFunction<JSDocEnumTag>(SyntaxKind.JSDocEnumTag); },
get updateJSDocEnumTag() { return getJSDocTypeLikeTagUpdateFunction<JSDocEnumTag>(SyntaxKind.JSDocEnumTag); },
get createJSDocAbstractTag() { return getJSDocSimpleTagCreateFunction<JSDocAbstractTag>(SyntaxKind.JSDocAbstractTag); },
get updateJSDocAbstractTag() { return getJSDocSimpleTagUpdateFunction<JSDocAbstractTag>(SyntaxKind.JSDocAbstractTag); },
get createJSDocAuthorTag() { return getJSDocSimpleTagCreateFunction<JSDocAuthorTag>(SyntaxKind.JSDocAuthorTag); },
get updateJSDocAuthorTag() { return getJSDocSimpleTagUpdateFunction<JSDocAuthorTag>(SyntaxKind.JSDocAuthorTag); },
get createJSDocClassTag() { return getJSDocSimpleTagCreateFunction<JSDocClassTag>(SyntaxKind.JSDocClassTag); },
Expand Down Expand Up @@ -5859,6 +5861,7 @@ namespace ts {
case SyntaxKind.JSDocReturnTag: return "returns";
case SyntaxKind.JSDocThisTag: return "this";
case SyntaxKind.JSDocEnumTag: return "enum";
case SyntaxKind.JSDocAbstractTag: return "abstract";
case SyntaxKind.JSDocAuthorTag: return "author";
case SyntaxKind.JSDocClassTag: return "class";
case SyntaxKind.JSDocPublicTag: return "public";
Expand Down
4 changes: 4 additions & 0 deletions src/compiler/factory/nodeTests.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -757,6 +757,10 @@ namespace ts {
return node.kind === SyntaxKind.JSDocAugmentsTag;
}

export function isJSDocAbstractTag(node: Node): node is JSDocAbstractTag {
return node.kind === SyntaxKind.JSDocAbstractTag;
}

export function isJSDocAuthorTag(node: Node): node is JSDocAuthorTag {
return node.kind === SyntaxKind.JSDocAuthorTag;
}
Expand Down
4 changes: 4 additions & 0 deletions src/compiler/parser.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -532,6 +532,7 @@ namespace ts {
case SyntaxKind.JSDocTypeLiteral:
return forEach((node as JSDocTypeLiteral).jsDocPropertyTags, cbNode);
case SyntaxKind.JSDocTag:
case SyntaxKind.JSDocAbstractTag:
case SyntaxKind.JSDocClassTag:
case SyntaxKind.JSDocPublicTag:
case SyntaxKind.JSDocPrivateTag:
Expand Down Expand Up @@ -7443,6 +7444,9 @@ namespace ts {

let tag: JSDocTag | undefined;
switch (tagName.escapedText) {
case "abstract":
tag = parseSimpleTag(start, factory.createJSDocAbstractTag, tagName, margin, indentText);
break;
case "author":
tag = parseAuthorTag(start, tagName, margin, indentText);
break;
Expand Down
7 changes: 7 additions & 0 deletions src/compiler/types.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -378,6 +378,7 @@ namespace ts {
JSDocTag,
JSDocAugmentsTag,
JSDocImplementsTag,
JSDocAbstractTag,
JSDocAuthorTag,
JSDocDeprecatedTag,
JSDocClassTag,
Expand Down Expand Up @@ -3166,6 +3167,10 @@ namespace ts {
readonly class: ExpressionWithTypeArguments & { readonly expression: Identifier | PropertyAccessEntityNameExpression };
}

export interface JSDocAbstractTag extends JSDocTag {
readonly kind: SyntaxKind.JSDocAbstractTag;
}

export interface JSDocAuthorTag extends JSDocTag {
readonly kind: SyntaxKind.JSDocAuthorTag;
}
Expand Down Expand Up @@ -7160,6 +7165,8 @@ namespace ts {
updateJSDocAugmentsTag(node: JSDocAugmentsTag, tagName: Identifier | undefined, className: JSDocAugmentsTag["class"], comment: string | undefined): JSDocAugmentsTag;
createJSDocImplementsTag(tagName: Identifier | undefined, className: JSDocImplementsTag["class"], comment?: string): JSDocImplementsTag;
updateJSDocImplementsTag(node: JSDocImplementsTag, tagName: Identifier | undefined, className: JSDocImplementsTag["class"], comment: string | undefined): JSDocImplementsTag;
createJSDocAbstractTag(tagName: Identifier | undefined, comment?: string): JSDocAbstractTag;
updateJSDocAbstractTag(node: JSDocAbstractTag, tagName: Identifier | undefined, comment: string | undefined): JSDocAbstractTag;
createJSDocAuthorTag(tagName: Identifier | undefined, comment?: string): JSDocAuthorTag;
updateJSDocAuthorTag(node: JSDocAuthorTag, tagName: Identifier | undefined, comment: string | undefined): JSDocAuthorTag;
createJSDocClassTag(tagName: Identifier | undefined, comment?: string): JSDocClassTag;
Expand Down
1 change: 1 addition & 0 deletions src/compiler/utilities.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4719,6 +4719,7 @@ namespace ts {
if (getJSDocPrivateTagNoCache(node)) flags |= ModifierFlags.Private;
if (getJSDocProtectedTagNoCache(node)) flags |= ModifierFlags.Protected;
if (getJSDocReadonlyTagNoCache(node)) flags |= ModifierFlags.Readonly;
if (getJSDocAbstractTagNoCache(node)) flags |= ModifierFlags.Abstract;
}
if (getJSDocDeprecatedTagNoCache(node)) flags |= ModifierFlags.Deprecated;
}
Expand Down
4 changes: 4 additions & 0 deletions src/compiler/utilitiesPublic.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -767,6 +767,10 @@ namespace ts {
return getFirstJSDocTag(node, isJSDocReadonlyTag, /*noCache*/ true);
}

export function getJSDocAbstractTagNoCache(node: Node): JSDocAbstractTag | undefined {
return getFirstJSDocTag(node, isJSDocAbstractTag, /*noCache*/ true);
}

/** Gets the JSDoc deprecated tag for the node if present */
export function getJSDocDeprecatedTag(node: Node): JSDocDeprecatedTag | undefined {
return getFirstJSDocTag(node, isJSDocDeprecatedTag);
Expand Down
Loading

0 comments on commit 1421fe1

Please sign in to comment.