Merge pull request #18706 from aozgaa/dev/aozgaa/JsDocExtendsSupport

support @extends in jsdoc

Author: aozgaa

src/compiler/checker.ts

@@ -20032,14 +20032,20 @@ namespace ts {
         }
 
         function checkJSDocAugmentsTag(node: JSDocAugmentsTag): void {
-            const cls = getJSDocHost(node);
-            if (!isClassDeclaration(cls) && !isClassExpression(cls)) {
-                error(cls, Diagnostics.JSDoc_augments_is_not_attached_to_a_class_declaration);
+            const classLike = getJSDocHost(node);
+            if (!isClassDeclaration(classLike) && !isClassExpression(classLike)) {
+                error(classLike, Diagnostics.JSDoc_augments_is_not_attached_to_a_class_declaration);
                 return;
             }
 
+            const augmentsTags = getAllJSDocTagsOfKind(classLike, SyntaxKind.JSDocAugmentsTag);
+            Debug.assert(augmentsTags.length > 0);
+            if (augmentsTags.length > 1) {
+                error(augmentsTags[1], Diagnostics.Class_declarations_cannot_have_more_than_one_augments_or_extends_tag);
+            }
+
             const name = getIdentifierFromEntityNameExpression(node.class.expression);
-            const extend = getClassExtendsHeritageClauseElement(cls);
+            const extend = getClassExtendsHeritageClauseElement(classLike);
             if (extend) {
                 const className = getIdentifierFromEntityNameExpression(extend.expression);
                 if (className && name.escapedText !== className.escapedText) {

src/compiler/diagnosticMessages.json

@@ -3531,6 +3531,10 @@
         "category": "Error",
         "code": 8024
     },
+    "Class declarations cannot have more than one `@augments` or `@extends` tag.": {
+        "category": "Error",
+        "code": 8025
+    },
     "Only identifiers/qualified-names with optional type arguments are currently supported in a class 'extends' clause.": {
         "category": "Error",
         "code": 9002

src/compiler/parser.ts

@@ -6373,6 +6373,7 @@ namespace ts {
                     if (tagName) {
                         switch (tagName.escapedText) {
                             case "augments":
+                            case "extends":
                                 tag = parseAugmentsTag(atToken, tagName);
                                 break;
                             case "class":

src/compiler/types.ts

@@ -2159,6 +2159,10 @@ namespace ts {
         kind: SyntaxKind.JSDocTag;
     }
 
+    /**
+     * Note that `@extends` is a synonym of `@augments`.
+     * Both tags are represented by this interface.
+     */
     export interface JSDocAugmentsTag extends JSDocTag {
         kind: SyntaxKind.JSDocAugmentsTag;
         class: ExpressionWithTypeArguments & { expression: Identifier | PropertyAccessEntityNameExpression };

src/compiler/utilities.ts

@@ -4241,6 +4241,12 @@ namespace ts {
         return find(tags, doc => doc.kind === kind);
     }
 
+    /** Gets all JSDoc tags of a specified kind, or undefined if not present. */
+    export function getAllJSDocTagsOfKind(node: Node, kind: SyntaxKind): ReadonlyArray<JSDocTag> | undefined {
+        const tags = getJSDocTags(node);
+        return filter(tags, doc => doc.kind === kind);
+    }
+
 }
 
 // Simple node tests of the form `node.kind === SyntaxKind.Foo`.

tests/baselines/reference/api/tsserverlibrary.d.ts

@@ -1442,6 +1442,10 @@ declare namespace ts {
     interface JSDocUnknownTag extends JSDocTag {
         kind: SyntaxKind.JSDocTag;
     }
+    /**
+     * Note that `@extends` is a synonym of `@augments`.
+     * Both tags are represented by this interface.
+     */
     interface JSDocAugmentsTag extends JSDocTag {
         kind: SyntaxKind.JSDocAugmentsTag;
         class: ExpressionWithTypeArguments & {
@@ -2866,6 +2870,8 @@ declare namespace ts {
     function getJSDocReturnType(node: Node): TypeNode | undefined;
     /** Get all JSDoc tags related to a node, including those on parent nodes. */
     function getJSDocTags(node: Node): ReadonlyArray<JSDocTag> | undefined;
+    /** Gets all JSDoc tags of a specified kind, or undefined if not present. */
+    function getAllJSDocTagsOfKind(node: Node, kind: SyntaxKind): ReadonlyArray<JSDocTag> | undefined;
 }
 declare namespace ts {
     function isNumericLiteral(node: Node): node is NumericLiteral;

tests/baselines/reference/api/typescript.d.ts

@@ -1442,6 +1442,10 @@ declare namespace ts {
     interface JSDocUnknownTag extends JSDocTag {
         kind: SyntaxKind.JSDocTag;
     }
+    /**
+     * Note that `@extends` is a synonym of `@augments`.
+     * Both tags are represented by this interface.
+     */
     interface JSDocAugmentsTag extends JSDocTag {
         kind: SyntaxKind.JSDocAugmentsTag;
         class: ExpressionWithTypeArguments & {
@@ -2921,6 +2925,8 @@ declare namespace ts {
     function getJSDocReturnType(node: Node): TypeNode | undefined;
     /** Get all JSDoc tags related to a node, including those on parent nodes. */
     function getJSDocTags(node: Node): ReadonlyArray<JSDocTag> | undefined;
+    /** Gets all JSDoc tags of a specified kind, or undefined if not present. */
+    function getAllJSDocTagsOfKind(node: Node, kind: SyntaxKind): ReadonlyArray<JSDocTag> | undefined;
 }
 declare namespace ts {
     function isNumericLiteral(node: Node): node is NumericLiteral;

tests/cases/fourslash/jsDocAugments.ts

@@ -20,4 +20,3 @@
 
 goTo.marker();
 verify.quickInfoIs("(local var) x: string");
-

tests/cases/fourslash/jsDocAugmentsAndExtends.ts

@@ -0,0 +1,37 @@
+///<reference path="fourslash.ts" />
+
+// @allowJs: true
+// @checkJs: true
+// @Filename: dummy.js
+
+//// /**
+////  * @augments {Thing<number>}
+////  * @extends {Thing<string>}
+////  */
+//// class MyStringThing extends Thing {
+////     constructor() {
+////         super();
+////         var x = this.mine;
+////         x/**/;
+////     }
+//// }
+
+// @Filename: declarations.d.ts
+//// declare class Thing<T> {
+////     mine: T;
+//// }
+
+// if more than one tag is present, report an error and take the type of the first entry.
+
+goTo.marker();
+verify.quickInfoIs("(local var) x: number");
+verify.getSemanticDiagnostics(
+`[
+  {
+    "message": "Class declarations cannot have more than one \`@augments\` or \`@extends\` tag.",
+    "start": 36,
+    "length": 24,
+    "category": "error",
+    "code": 8025
+  }
+]`);

tests/cases/fourslash/jsDocExtends.ts

@@ -0,0 +1,22 @@
+///<reference path="fourslash.ts" />
+
+// @allowJs: true
+// @Filename: dummy.js
+
+//// /**
+////  * @extends {Thing<string>}
+////  */
+//// class MyStringThing extends Thing {
+////     constructor() {
+////         var x = this.mine;
+////         x/**/;
+////     }
+//// }
+
+// @Filename: declarations.d.ts
+//// declare class Thing<T> {
+////     mine: T;
+//// }
+
+goTo.marker();
+verify.quickInfoIs("(local var) x: string");