Add special cases for this

Resolves #2458

CHANGELOG.md

@@ -3,6 +3,9 @@
 ## Features
 
 -   Extended reflection preview view for interfaces to include type parameters, #2455.
+-   Added special cases for converting methods which are documented as returning `this` or accepting `this` as a parameter, #2458.
+    Note: This will only happen if a method is declared as `method(): this`, it will not happen if the method implicitly returns `this`
+    as the compiler strips that information when creating types for a class instance.
 
 ### Bug Fixes
 

package.json

@@ -64,6 +64,7 @@
     "test": "mocha --config .config/mocha.fast.json",
     "test:cov": "c8 mocha --config .config/mocha.fast.json",
     "doc:c": "node bin/typedoc --tsconfig src/test/converter/tsconfig.json",
+    "doc:cd": "node --inspect-brk bin/typedoc --tsconfig src/test/converter/tsconfig.json",
     "doc:c2": "node bin/typedoc --tsconfig src/test/converter2/tsconfig.json",
     "doc:c2d": "node --inspect-brk bin/typedoc --tsconfig src/test/converter2/tsconfig.json",
     "example": "cd example && node ../bin/typedoc",

src/lib/converter/factories/signature.ts

@@ -96,6 +96,8 @@ export function createSignature(
         sigRef.type = convertPredicate(predicate, sigRefCtx);
     } else if (kind == ReflectionKind.SetSignature) {
         sigRef.type = new IntrinsicType("void");
+    } else if (declaration?.type?.kind === ts.SyntaxKind.ThisType) {
+        sigRef.type = new IntrinsicType("this");
     } else {
         sigRef.type = context.converter.convertType(
             sigRefCtx,
@@ -171,10 +173,18 @@ function convertParameters(
             type = param.type;
         }
 
-        paramRefl.type = context.converter.convertType(
-            context.withScope(paramRefl),
-            type,
-        );
+        if (
+            declaration &&
+            ts.isParameter(declaration) &&
+            declaration.type?.kind === ts.SyntaxKind.ThisType
+        ) {
+            paramRefl.type = new IntrinsicType("this");
+        } else {
+            paramRefl.type = context.converter.convertType(
+                context.withScope(paramRefl),
+                type,
+            );
+        }
 
         let isOptional = false;
         if (declaration) {
@@ -384,8 +394,6 @@ export function convertTemplateParameterNodes(
             return paramRefl;
         });
     });
-    const params = (nodes ?? []).flatMap((tag) => tag.typeParameters);
-    return convertTypeParameterNodes(context, params);
 }
 
 function getVariance(

src/lib/models/reflections/abstract.ts

@@ -527,6 +527,8 @@ export abstract class Reflection {
     /**
      * Return a string representation of this reflection and all of its children.
      *
+     * Note: This is intended as a debug tool only, output may change between patch versions.
+     *
      * @param indent  Used internally to indent child reflections.
      */
     toStringHierarchy(indent = "") {

src/lib/models/reflections/declaration.ts

@@ -279,7 +279,7 @@ export class DeclarationReflection extends ContainerReflection {
         }
 
         if (this.type) {
-            result += ":" + this.type.toString();
+            result += ": " + this.type.toString();
         }
 
         return result;

src/lib/models/reflections/parameter.ts

@@ -33,7 +33,9 @@ export class ParameterReflection extends Reflection {
      * Return a string representation of this reflection.
      */
     override toString() {
-        return super.toString() + (this.type ? ":" + this.type.toString() : "");
+        return (
+            super.toString() + (this.type ? ": " + this.type.toString() : "")
+        );
     }
 
     override toObject(serializer: Serializer): JSONOutput.ParameterReflection {

src/lib/models/reflections/signature.ts

@@ -101,7 +101,7 @@ export class SignatureReflection extends Reflection {
         }
 
         if (this.type) {
-            result += ":" + this.type.toString();
+            result += ": " + this.type.toString();
         }
 
         return result;

src/test/behavior.c2.test.ts

@@ -19,7 +19,7 @@ import {
 import { join } from "path";
 import { existsSync } from "fs";
 import { clearCommentCache } from "../lib/converter/comments";
-import { query } from "./utils";
+import { query, querySig } from "./utils";
 
 type NameTree = { [name: string]: NameTree };
 
@@ -1004,4 +1004,25 @@ describe("Behavior Tests", () => {
         const MergedType = query(convert("resolutionMode"), "MergedType");
         equal(MergedType.children?.map((child) => child.name), ["cjs", "esm"]);
     });
+
+    it("Special cases some `this` type occurrences", () => {
+        const project = convert("thisType");
+        equal(query(project, "ThisClass.prop").type?.toString(), "ThisClass"); // Not special cased
+        equal(
+            querySig(project, "ThisClass.returnThisImplicit").type?.toString(),
+            "ThisClass",
+        ); // Not special cased
+
+        equal(
+            querySig(project, "ThisClass.returnThis").type?.toString(),
+            "this",
+        );
+        equal(
+            querySig(
+                project,
+                "ThisClass.paramThis",
+            ).parameters?.[0].type?.toString(),
+            "this",
+        );
+    });
 });