Improve support for @class

Resolves multiple bugs reported in #2914

Author: Gerrit0

CHANGELOG.md

@@ -6,6 +6,10 @@ title: Changelog
 
 ### Bug Fixes
 
+- Variables using `@class` now correctly handle `@category`, #2914.
+- Variables using `@class` now include constructor parameters, #2914.
+- Variables using `@class` with a generic first constructor function now adopt
+  that function's type parameters as the class type parameters, #2914.
 - Inlining types can now handle more type variants, #2920.
 - API: `toString` on types containing index signatures now behave correctly, #2917.
 

site/tags/class.md

@@ -12,6 +12,12 @@ will result in all "dynamic" properties being expanded to real properties.
 TypeDoc will also ignore types/interfaces declared with the same name as
 variables annotated with `@class`.
 
+If the constructor function has more than one overload, TypeDoc will use
+the return type for the first overload to determine the shape of the class.
+
+If the constructor function is generic, the type parameters will be lifted
+up from the constructor function to become class type parameters.
+
 ## Example
 
 ```ts

src/lib/converter/factories/signature.ts

@@ -159,13 +159,31 @@ export function createConstructSignatureWithType(
 
     if (declaration) {
         sigRef.comment = context.getSignatureComment(declaration);
+        if (sigRef.comment?.discoveryId === context.scope.parent?.comment?.discoveryId) {
+            delete sigRef.comment;
+        }
     }
 
-    sigRef.typeParameters = convertTypeParameters(
+    const parameterSymbols: Array<ts.Symbol & { type?: ts.Type }> = signature.thisParameter
+        ? [signature.thisParameter, ...signature.parameters]
+        : [...signature.parameters];
+
+    // Prevent a `this` parameter from appearing on constructor signature
+    // as TS disallows them on regular classes.
+    if (parameterSymbols[0]?.name === "this") {
+        parameterSymbols.shift();
+    }
+
+    sigRef.parameters = convertParameters(
         sigRefCtx,
         sigRef,
-        signature.typeParameters,
+        parameterSymbols,
+        declaration?.parameters,
     );
+    sigRef.parameters = convertParameters(sigRefCtx, sigRef, parameterSymbols, undefined);
+
+    // Do NOT convert type parameters here, they go on the class itself in the @class case
+    // See #2914.
 
     sigRef.type = ReferenceType.createResolvedReference(
         context.scope.parent!.name,
@@ -368,7 +386,7 @@ function checkForDestructuredParameterDefaults(
     }
 }
 
-function convertTypeParameters(
+export function convertTypeParameters(
     context: Context,
     parent: Reflection,
     parameters: readonly ts.TypeParameter[] | undefined,

src/lib/converter/symbols.ts

@@ -14,7 +14,12 @@ import { getEnumFlags, hasAllFlags, hasAnyFlag, i18n, removeFlag } from "#utils"
 import type { Context } from "./context.js";
 import { convertDefaultValue } from "./convert-expression.js";
 import { convertIndexSignatures } from "./factories/index-signature.js";
-import { createConstructSignatureWithType, createSignature, createTypeParamReflection } from "./factories/signature.js";
+import {
+    convertTypeParameters,
+    createConstructSignatureWithType,
+    createSignature,
+    createTypeParamReflection,
+} from "./factories/signature.js";
 import { convertJsDocAlias, convertJsDocCallback } from "./jsdoc.js";
 import { getHeritageTypes } from "./utils/nodes.js";
 import { removeUndefined } from "./utils/reflections.js";
@@ -1277,6 +1282,10 @@ function convertSymbolAsClass(
             createConstructSignatureWithType(constructContext, sig, reflection);
         }
 
+        // Take the type parameters from the first constructor signature and use
+        // them as the type parameters for the class, #2914
+        reflection.typeParameters = convertTypeParameters(rc, reflection, ctors[0].getTypeParameters());
+
         const instType = ctors[0].getReturnType();
         convertSymbols(rc, instType.getProperties());
 

src/test/converter2/issues/gh2914.ts

@@ -0,0 +1,17 @@
+/**
+ * Description
+ * @class
+ * @category Bug
+ */
+export declare const Bug1: new () => { x: string };
+
+/** @class */
+export declare const Bug2: new (x: string) => {};
+
+/** @class */
+export declare const Bug3: new <T extends string>() => {
+    x: T;
+};
+
+/** @class */
+export declare const Bug4: new <T extends () => U, U extends string>(x: T) => T;

src/test/issues.c2.test.ts

@@ -2043,6 +2043,43 @@ describe("Issue Tests", () => {
         equal(exp.type?.toString(), "never[]");
     });
 
+    it("#2914 does not categorize @class constructor if class is categorized", () => {
+        app.options.setValue("categorizeByGroup", false);
+        const project = convert();
+        const Bug1 = query(project, "Bug1");
+        equal(Bug1.children?.map(c => c.name), ["constructor", "x"]);
+        equal(Bug1.categories === undefined, true, "Should not have categories");
+
+        equal(project.categories?.length, 2);
+        equal(project.categories[0].title, "Bug");
+        equal(project.categories[1].title, "Other");
+    });
+
+    it("#2914 includes constructor parameters", () => {
+        app.options.setValue("categorizeByGroup", false);
+        const project = convert();
+        const ctor = querySig(project, "Bug2.constructor");
+        equal(ctor.parameters?.length, 1);
+        equal(ctor.parameters[0].name, "x");
+        equal(ctor.parameters[0].type?.toString(), "string");
+    });
+
+    it("#2914 converts constructor type parameters as class type parameters", () => {
+        const project = convert();
+        const Bug3 = query(project, "Bug3");
+        equal(Bug3.typeParameters?.length, 1);
+        equal(Bug3.typeParameters[0].type?.toString(), "string");
+        const ctor = querySig(project, "Bug3.constructor");
+        equal(ctor.typeParameters, undefined);
+    });
+
+    it("#2914 includes call signatures on the class type", () => {
+        const project = convert();
+        const Bug4 = query(project, "Bug4");
+        equal(Bug4.signatures?.length, 1);
+        equal(Bug4.signatures[0].type?.toString(), "U");
+    });
+
     it("#2917 stringifies index signatures", () => {
         const project = convert();
         const data = query(project, "Foo.data");