Handle @inline on more types

Resolves #2920

Author: Gerrit0

CHANGELOG.md

@@ -6,6 +6,7 @@ title: Changelog
 
 ### Bug Fixes
 
+- Inlining types can now handle more type variants, #2920.
 - API: `toString` on types containing index signatures now behave correctly, #2917.
 
 ## v0.28.1 (2025-03-20)

site/tags/inline.md

@@ -13,7 +13,10 @@ TypeDoc converts references to type aliases and interfaces.
 
 The `@inline` tag may be placed on type aliases and interfaces. When a type is
 annotated with `@inline` and the type is referenced, TypeDoc will attempt to inline
-the referenced type within the other type.
+the referenced type within the other type. TypeDoc is unable to inline some types,
+notably type references with type parameters in some cases, and may make incorrect
+guesses about the shape of types which aren't object literals, unions, intersections,
+or literals. Please report a bug if `@inline` incorrectly converts a type.
 
 > [!note]
 > Use of this tag can _significantly_ increase the size of your generated

src/lib/converter/types.ts

@@ -653,6 +653,7 @@ const typeLiteralConverter: TypeConverter<ts.TypeLiteralNode> = {
         return new ReflectionType(reflection);
     },
     convertType(context, type) {
+        // Don't use the third parameter here or you break convertTypeInline
         const symbol = type.getSymbol();
         const reflection = new DeclarationReflection(
             "__type",
@@ -764,16 +765,7 @@ const referenceConverter: TypeConverter<
             !node.typeArguments &&
             context.shouldInline(symbol, name)
         ) {
-            // typeLiteralConverter doesn't use the node, so we can get away with lying here.
-            // This might not actually be safe, it appears that it is in the relatively small
-            // amount of testing I've done with it, but I wouldn't be surprised if someone manages
-            // to find a crash.
-            return typeLiteralConverter.convertType(
-                context,
-                type,
-                null!,
-                undefined,
-            );
+            return convertTypeInlined(context, type);
         }
 
         const ref = context.createSymbolReference(
@@ -808,16 +800,7 @@ const referenceConverter: TypeConverter<
         }
 
         if (context.shouldInline(symbol, name)) {
-            // typeLiteralConverter doesn't use the node, so we can get away with lying here.
-            // This might not actually be safe, it appears that it is in the relatively small
-            // amount of testing I've done with it, but I wouldn't be surprised if someone manages
-            // to find a crash.
-            return typeLiteralConverter.convertType(
-                context,
-                type,
-                null!,
-                undefined,
-            );
+            return convertTypeInlined(context, type);
         }
 
         const ref = context.createSymbolReference(
@@ -1259,3 +1242,36 @@ function normalizeUnion(types: SomeType[]) {
         );
     }
 }
+
+function convertTypeInlined(context: Context, type: ts.Type): SomeType {
+    if (type.isUnion()) {
+        const types = type.types.map(type => convertType(context, type));
+        return new UnionType(types);
+    }
+
+    if (type.isIntersection()) {
+        const types = type.types.map(type => convertType(context, type));
+        return new IntersectionType(types);
+    }
+
+    if (type.isLiteral()) {
+        return new LiteralType(
+            typeof type.value === "object"
+                ? BigInt(type.value.base10Value) * (type.value.negative ? -1n : 1n)
+                : type.value,
+        );
+    }
+
+    if (context.checker.isArrayType(type)) {
+        const elementType = convertType(context, context.checker.getTypeArguments(type as ts.TypeReference)[0]);
+        return new ArrayType(elementType);
+    }
+
+    // typeLiteralConverter doesn't use the node, so we can get away with lying here.
+    return typeLiteralConverter.convertType(
+        context,
+        type,
+        null!,
+        undefined,
+    );
+}

src/test/converter2/issues/gh2920.ts

@@ -0,0 +1,16 @@
+type EndpointIdentifier = "main" | "test";
+
+/**
+ * @inlineType EndpointIdentifier
+ */
+export function test(endpoint: EndpointIdentifier) {}
+
+type InlinedConditional<T> = T extends string ? 1 : 2;
+
+/** @inlineType InlinedConditional */
+export type NotInlined = InlinedConditional<string>;
+
+/** @inline */
+type StrArr = string[];
+
+export type InlineArray = StrArr;

src/test/issues.c2.test.ts

@@ -2050,4 +2050,16 @@ describe("Issue Tests", () => {
         const mixed = query(project, "Foo.mixed");
         equal(mixed.type?.toString(), "{ (): string; a: string; [key: string]: any }");
     });
+
+    it("#2920 handles inlining union types", () => {
+        const project = convert();
+        const test = querySig(project, "test");
+        equal(test.parameters?.[0].type?.toString(), '"main" | "test"');
+
+        const test2 = query(project, "NotInlined");
+        equal(test2.type?.toString(), "InlinedConditional<string>");
+
+        const test3 = query(project, "InlineArray");
+        equal(test3.type?.toString(), "string[]");
+    });
 });