feat: #547 - Wrap JSDocSignature and JSDocType.

Still need to add more methods on JSDocSignature, but not going to bother for the time being.

lib/ts-morph.d.ts

@@ -1195,11 +1195,21 @@ export declare class TypeGuards {
      * @param node - Node to check.
      */
     static isJSDocReturnTag(node: Node): node is JSDocReturnTag;
+    /**
+     * Gets if the node is a JSDocSignature.
+     * @param node - Node to check.
+     */
+    static isJSDocSignature(node: Node): node is JSDocSignature;
     /**
      * Gets if the node is a JSDocTag.
      * @param node - Node to check.
      */
     static isJSDocTag(node: Node): node is JSDocTag;
+    /**
+     * Gets if the node is a JSDocType.
+     * @param node - Node to check.
+     */
+    static isJSDocType(node: Node): node is JSDocType;
     /**
      * Gets if the node is a JSDocTypeExpression.
      * @param node - Node to check.
@@ -5014,6 +5024,16 @@ export declare class JSDocReturnTag extends JSDocTag<ts.JSDocReturnTag> {
     getTypeExpression(): JSDocTypeExpression | undefined;
 }
 
+/**
+ * JS doc signature node.
+ */
+export declare class JSDocSignature extends JSDocType<ts.JSDocSignature> {
+    /**
+     * Gets the type node of the JS doc signature.
+     */
+    getTypeNode(): JSDocReturnTag | undefined;
+}
+
 /**
  * JS doc tag node.
  */
@@ -5049,6 +5069,12 @@ export declare class JSDocTagInfo {
     getText(): string | undefined;
 }
 
+/**
+ * JS doc type node.
+ */
+export declare class JSDocType<T extends ts.JSDocType = ts.JSDocType> extends TypeNode<T> {
+}
+
 /**
  * JS doc type def tag node.
  */
@@ -6435,11 +6461,12 @@ export interface ImplementedKindToNodeMappings {
     [SyntaxKind.IndexSignature]: IndexSignatureDeclaration;
     [SyntaxKind.InterfaceDeclaration]: InterfaceDeclaration;
     [SyntaxKind.IntersectionType]: IntersectionTypeNode;
-    [SyntaxKind.JSDocTag]: JSDocUnknownTag;
-    [SyntaxKind.FirstJSDocTagNode]: JSDocUnknownTag;
     [SyntaxKind.JSDocAugmentsTag]: JSDocAugmentsTag;
     [SyntaxKind.JSDocClassTag]: JSDocClassTag;
     [SyntaxKind.JSDocReturnTag]: JSDocReturnTag;
+    [SyntaxKind.JSDocSignature]: JSDocSignature;
+    [SyntaxKind.JSDocTag]: JSDocUnknownTag;
+    [SyntaxKind.FirstJSDocTagNode]: JSDocUnknownTag;
     [SyntaxKind.JSDocTypeExpression]: JSDocTypeExpression;
     [SyntaxKind.FirstJSDocNode]: JSDocTypeExpression;
     [SyntaxKind.JSDocTypeTag]: JSDocTypeTag;

src/compiler/ast/doc/JSDocSignature.ts

@@ -0,0 +1,16 @@
+import { ts } from "../../../typescript";
+import { JSDocType } from "./JSDocType";
+
+/**
+ * JS doc signature node.
+ */
+export class JSDocSignature extends JSDocType<ts.JSDocSignature> {
+    /**
+     * Gets the type node of the JS doc signature.
+     */
+    getTypeNode() {
+        return this._getNodeFromCompilerNodeIfExists(this.compilerNode.type);
+    }
+
+    // todo: more methods
+}

src/compiler/ast/doc/JSDocType.ts

@@ -0,0 +1,8 @@
+import { ts } from "../../../typescript";
+import { TypeNode } from "../type";
+
+/**
+ * JS doc type node.
+ */
+export class JSDocType<T extends ts.JSDocType = ts.JSDocType> extends TypeNode<T> {
+}

src/compiler/ast/doc/index.ts

@@ -5,8 +5,10 @@ export * from "./JSDocClassTag";
 export * from "./JSDocParameterTag";
 export * from "./JSDocPropertyTag";
 export * from "./JSDocReturnTag";
+export * from "./JSDocSignature";
 export * from "./JSDocTag";
 export * from "./JSDocTagInfo";
+export * from "./JSDocType";
 export * from "./JSDocTypedefTag";
 export * from "./JSDocTypeTag";
 export * from "./JSDocUnknownTag";

src/compiler/ast/kindToNodeMappings.ts

@@ -65,11 +65,12 @@ export interface ImplementedKindToNodeMappings {
     [SyntaxKind.IndexSignature]: compiler.IndexSignatureDeclaration;
     [SyntaxKind.InterfaceDeclaration]: compiler.InterfaceDeclaration;
     [SyntaxKind.IntersectionType]: compiler.IntersectionTypeNode;
-    [SyntaxKind.JSDocTag]: compiler.JSDocUnknownTag;
-    [SyntaxKind.FirstJSDocTagNode]: compiler.JSDocUnknownTag;
     [SyntaxKind.JSDocAugmentsTag]: compiler.JSDocAugmentsTag;
     [SyntaxKind.JSDocClassTag]: compiler.JSDocClassTag;
     [SyntaxKind.JSDocReturnTag]: compiler.JSDocReturnTag;
+    [SyntaxKind.JSDocSignature]: compiler.JSDocSignature;
+    [SyntaxKind.JSDocTag]: compiler.JSDocUnknownTag;
+    [SyntaxKind.FirstJSDocTagNode]: compiler.JSDocUnknownTag;
     [SyntaxKind.JSDocTypeExpression]: compiler.JSDocTypeExpression;
     [SyntaxKind.FirstJSDocNode]: compiler.JSDocTypeExpression;
     [SyntaxKind.JSDocTypeTag]: compiler.JSDocTypeTag;

src/factories/kindToWrapperMappings.ts

@@ -66,10 +66,11 @@ export const kindToWrapperMappings: { [key: number]: unknown } = {
     [SyntaxKind.IndexSignature]: compiler.IndexSignatureDeclaration,
     [SyntaxKind.InterfaceDeclaration]: compiler.InterfaceDeclaration,
     [SyntaxKind.IntersectionType]: compiler.IntersectionTypeNode,
-    [SyntaxKind.JSDocTag]: compiler.JSDocUnknownTag,
     [SyntaxKind.JSDocAugmentsTag]: compiler.JSDocAugmentsTag,
     [SyntaxKind.JSDocClassTag]: compiler.JSDocClassTag,
     [SyntaxKind.JSDocReturnTag]: compiler.JSDocReturnTag,
+    [SyntaxKind.JSDocSignature]: compiler.JSDocSignature,
+    [SyntaxKind.JSDocTag]: compiler.JSDocUnknownTag,
     [SyntaxKind.JSDocTypeExpression]: compiler.JSDocTypeExpression,
     [SyntaxKind.JSDocTypeTag]: compiler.JSDocTypeTag,
     [SyntaxKind.JSDocTypedefTag]: compiler.JSDocTypedefTag,

src/tests/compiler/ast/doc/jsDocReturnTagTests.ts

@@ -1,11 +1,11 @@
-import {expect} from "chai";
-import {JSDocReturnTag, TypeGuards} from "../../../../main";
-import {getInfoFromText} from "../../testHelpers";
+import { expect } from "chai";
+import { JSDocReturnTag } from "../../../../compiler";
+import { SyntaxKind } from "../../../../typescript";
+import { getInfoFromTextWithDescendant } from "../../testHelpers";
 
 describe(nameof(JSDocReturnTag), () => {
     function getInfo(text: string) {
-        const info = getInfoFromText(text);
-        return { descendant: info.sourceFile.getFirstDescendantOrThrow(TypeGuards.isJSDocReturnTag), ...info };
+        return getInfoFromTextWithDescendant<JSDocReturnTag>(text, SyntaxKind.JSDocReturnTag);
     }
 
     describe(nameof<JSDocReturnTag>(d => d.getTypeExpression), () => {

src/tests/compiler/ast/doc/jsDocSignatureTests.ts

@@ -0,0 +1,28 @@
+import { expect } from "chai";
+import { JSDocSignature } from "../../../../compiler";
+import { SyntaxKind } from "../../../../typescript";
+import { getInfoFromTextWithDescendant } from "../../testHelpers";
+
+describe(nameof(JSDocSignature), () => {
+    function getInfo(text: string) {
+        return getInfoFromTextWithDescendant<JSDocSignature>(text, SyntaxKind.JSDocSignature);
+    }
+
+    describe(nameof<JSDocSignature>(d => d.getTypeNode), () => {
+        function doTest(text: string, expected: string | undefined) {
+            const { descendant } = getInfo(text);
+            if (expected == null)
+                expect(descendant.getTypeNode()).to.be.undefined;
+            else
+                expect(descendant.getTypeNode()!.getText()).to.equal(expected);
+        }
+
+        it("should get when it exists", () => {
+            doTest("/**\n * @callback cb\n * @return {string}\n */\nlet x;", "@return {string}");
+        });
+
+        it("should be undefined when not exists", () => {
+            doTest("/**\n * @callback cb\n */\nlet x;", undefined);
+        });
+    });
+});

src/utils/TypeGuards.ts

@@ -1103,6 +1103,14 @@ export class TypeGuards {
         return node.getKind() === SyntaxKind.JSDocReturnTag;
     }
 
+    /**
+     * Gets if the node is a JSDocSignature.
+     * @param node - Node to check.
+     */
+    static isJSDocSignature(node: compiler.Node): node is compiler.JSDocSignature {
+        return node.getKind() === SyntaxKind.JSDocSignature;
+    }
+
     /**
      * Gets if the node is a JSDocTag.
      * @param node - Node to check.
@@ -1123,6 +1131,14 @@ export class TypeGuards {
         }
     }
 
+    /**
+     * Gets if the node is a JSDocType.
+     * @param node - Node to check.
+     */
+    static isJSDocType(node: compiler.Node): node is compiler.JSDocType {
+        return node.getKind() === SyntaxKind.JSDocSignature;
+    }
+
     /**
      * Gets if the node is a JSDocTypeExpression.
      * @param node - Node to check.
@@ -2468,6 +2484,7 @@ export class TypeGuards {
     static isTypeNode(node: compiler.Node): node is compiler.TypeNode {
         switch (node.getKind()) {
             case SyntaxKind.TypePredicate:
+            case SyntaxKind.JSDocSignature:
             case SyntaxKind.ArrayType:
             case SyntaxKind.ConstructorType:
             case SyntaxKind.ExpressionWithTypeArguments:

wrapped-nodes.md

@@ -6,7 +6,7 @@ The disadvantage to a node not being wrapped is that it won't have helper method
 
 ## Exist
 
-**Total:** 168
+**Total:** 170
 
 * [ArrayBindingPattern](src/compiler/ast/binding/ArrayBindingPattern.ts)
     * :heavy_check_mark: elements
@@ -184,9 +184,14 @@ The disadvantage to a node not being wrapped is that it won't have helper method
 * [JSDocPropertyTag](src/compiler/ast/doc/JSDocPropertyTag.ts)
 * [JSDocReturnTag](src/compiler/ast/doc/JSDocReturnTag.ts)
     * :heavy_check_mark: typeExpression
+* [JSDocSignature](src/compiler/ast/doc/JSDocSignature.ts)
+    * :x: typeParameters
+    * :x: parameters
+    * :heavy_check_mark: type
 * [JSDocTag](src/compiler/ast/doc/JSDocTag.ts)
     * :heavy_check_mark: tagName
     * :heavy_check_mark: comment
+* [JSDocType](src/compiler/ast/doc/JSDocType.ts)
 * [JSDocTypeExpression](src/compiler/ast/doc/JSDocTypeExpression.ts)
     * :heavy_check_mark: type
 * [JSDocTypeTag](src/compiler/ast/doc/JSDocTypeTag.ts)
@@ -424,7 +429,7 @@ The disadvantage to a node not being wrapped is that it won't have helper method
 
 ## Not Exist
 
-**Total:** 55
+**Total:** 53
 
 * BigIntLiteral
 * Bundle
@@ -445,10 +450,8 @@ The disadvantage to a node not being wrapped is that it won't have helper method
 * JSDocNullableType
 * JSDocOptionalType
 * JSDocPropertyLikeTag
-* JSDocSignature
 * JSDocTemplateTag
 * JSDocThisTag
-* JSDocType
 * JSDocTypeLiteral
 * JSDocUnknownType
 * JSDocVariadicType