Support @preventInline and @inlineType tags

Ref: #2862

Author: Gerrit0

CHANGELOG.md

@@ -50,6 +50,7 @@ title: Changelog
 - TypeDoc will now warn if an option which should only be set at the root level is set in `packageOptions`, #2878.
 - Introduced `@function` tag to force TypeDoc to convert variable declarations with a type annotation as functions, #2881.
 - Exposed a `TypeDoc` global object in the HTML theme which can be used to prevent TypeDoc from using `localStorage`, #2872.
+- Introduced `@preventInline` and `@inlineType` tags for further control extending the `@inline` tag, #2862.
 
 ### Bug Fixes
 

site/options/package-options.md

@@ -103,7 +103,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`hostedBaseUrl`](output.md#hostedbaseurl)                                             | Root     |                                                            |
 | [`useHostedBaseUrlForAbsoluteLinks`](output.md#usehostedbaseurlforabsolutelinks)       | Root     |                                                            |
 | [`useFirstParagraphOfCommentAsSummary`](output.md#usefirstparagraphofcommentassummary) | Root     |                                                            |
-| [`includeHierarchySummary`](input.md#includehierarchysummary)                          | Root     |                                                            |
+| [`includeHierarchySummary`](output.md#includehierarchysummary)                         | Root     |                                                            |
 
 ## Comment Options
 

site/tags.md

@@ -116,10 +116,12 @@ examples for how to use the export ([`@example`](./tags/example.md)).
 - [`@example`](./tags/example.md)
 - [`@group`, `@groupDescription`, `@showGroups`, `@hideGroups`](./tags/group.md)
 - [`@import`](./tags/import.md)
+- [`@inlineType`](./tags/inline.md#inlinetype)
 - [`@license`](./tags/license.md)
 - [`@mergeModuleWith`](./tags/mergeModuleWith.md)
 - [`@module`](./tags/module.md)
 - [`@param`](./tags/param.md)
+- [`@preventInline`](./tags/inline.md#preventinline)
 - [`@privateRemarks`](./tags/privateRemarks.md)
 - [`@property`, `@prop`](./tags/property.md)
 - [`@remarks`](./tags/remarks.md)

site/tags/inline.md

@@ -2,7 +2,12 @@
 title: "@inline"
 ---
 
-# @inline
+# Inline Tags
+
+The `@inline`, `@inlineType` and `@preventInline` tags can be used to control how
+TypeDoc converts references to type aliases and interfaces.
+
+## @inline
 
 **Tag Kind:** [Modifier](../tags.md#modifier-tags)
 
@@ -15,7 +20,7 @@ the referenced type within the other type.
 > documentation if it is applied to commonly used types as it will result in
 > inlining the comments for those types everywhere they are referenced.
 
-## Example
+### Example
 
 ```tsx
 /**
@@ -27,13 +32,70 @@ export type HelloProps = {
 };
 
 /**
- * Hello component
+ * Hello component - HelloProps will be inlined here as
+ * if you had written `Hello(props: { name: string })`
+ */
+export function Hello(props: HelloProps) {
+    return <span>Hello {props.name}!</span>;
+}
+```
+
+## @inlineType
+
+**Tag Kind:** [Block](../tags.md#block-tags)
+
+The `@inlineType` block tag can be used to selectively inline a type reference
+without inlining it everywhere. It should specify the type name without type
+arguments.
+
+### Example
+
+```ts
+export type HelloProps = {
+    name: string;
+};
+
+/**
+ * Hello component - HelloProps will be inlined here as
+ * if you had written `Hello(props: { name: string })`
+ * @inlineType HelloProps
  */
 export function Hello(props: HelloProps) {
     return <span>Hello {props.name}!</span>;
 }
 ```
 
+## @preventInline
+
+**Tag Kind:** [Block](../tags.md#block-tags)
+
+The `@preventInline` block tag can be used to instruct TypeDoc to not inline a
+tag which has been inlined with `@inline` or `@preventInline`. Note that TypeDoc
+will be unable to produce a type reference instead of an inlined type if
+TypeScript does not produce a named reference to begin with. If you remove
+`@inline` and the type is still inlined in your type, `@preventInline` cannot
+prevent the expansion.
+
+### Example
+
+```tsx
+/**
+ * @inline
+ */
+export type HelloProps = {
+    /** Name property docs */
+    name: string;
+};
+
+/**
+ * Hello component - HelloProps will NOT be inlined here
+ * @preventInline HelloProps
+ */
+export function Hello2(props: HelloProps) {
+    return <span>Hello {props.name}!</span>;
+}
+```
+
 ## See Also
 
 - The [`@expand`](expand.md) tag

src/lib/converter/context.ts

@@ -2,6 +2,7 @@ import { ok as assert } from "assert";
 import ts from "typescript";
 
 import {
+    Comment,
     ContainerReflection,
     DeclarationReflection,
     type DocumentReflection,
@@ -69,6 +70,8 @@ export class Context {
     convertingTypeNode = false; // Inherited by withScope
     convertingClassOrInterface = false; // Not inherited
     shouldBeStatic = false; // Not inherited
+    inlineType = new Set<string>(); // Inherited by withScope
+    preventInline = new Set<string>(); // Inherited by withScope
 
     private reflectionIdToSymbolMap = new Map<number, ts.Symbol>();
 
@@ -396,6 +399,15 @@ export class Context {
         );
     }
 
+    shouldInline(symbol: ts.Symbol, name: string): boolean {
+        if (this.preventInline.has(name)) return false;
+        if (this.inlineType.has(name)) return true;
+
+        return this
+            .getComment(symbol, ReflectionKind.Interface)
+            ?.hasModifier("@inline") ?? false;
+    }
+
     public withScope(scope: Reflection): Context {
         assert(scope.parent === this.scope || scope === this.scope, "Incorrect context used for withScope");
 
@@ -408,6 +420,17 @@ export class Context {
         context.convertingTypeNode = this.convertingTypeNode;
         context.setActiveProgram(this._program);
         context.reflectionIdToSymbolMap = this.reflectionIdToSymbolMap;
+        context.preventInline = new Set(this.preventInline);
+        context.inlineType = new Set(this.inlineType);
+
+        for (const tag of scope.comment?.blockTags || []) {
+            if (tag.tag === "@preventInline") {
+                context.preventInline.add(Comment.combineDisplayParts(tag.content));
+            } else if (tag.tag === "@inlineType") {
+                context.inlineType.add(Comment.combineDisplayParts(tag.content));
+            }
+        }
+
         return context;
     }
 }

src/lib/converter/factories/signature.ts

@@ -48,7 +48,6 @@ export function createSignature(
     if (context.shouldBeStatic) {
         sigRef.setFlag(ReflectionFlag.Static);
     }
-    const sigRefCtx = context.withScope(sigRef);
     if (symbol && declaration) {
         context.project.registerSymbolId(
             sigRef,
@@ -74,6 +73,7 @@ export function createSignature(
         }
     }
 
+    const sigRefCtx = context.withScope(sigRef);
     sigRef.typeParameters = convertTypeParameters(
         sigRefCtx,
         sigRef,

src/lib/converter/types.ts

@@ -756,14 +756,13 @@ const referenceConverter: TypeConverter<
         }
 
         const symbol = context.expectSymbolAtLocation(node.typeName);
+        const name = node.typeName.getText();
 
         // Ignore @inline if there are type arguments, as they won't be resolved
         // in the type we just retrieved from node.typeName.
         if (
             !node.typeArguments &&
-            context
-                .getComment(symbol, ReflectionKind.Interface)
-                ?.hasModifier("@inline")
+            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
@@ -777,8 +776,6 @@ const referenceConverter: TypeConverter<
             );
         }
 
-        const name = node.typeName.getText();
-
         const ref = context.createSymbolReference(
             context.resolveAliasedSymbol(symbol),
             context,
@@ -803,11 +800,14 @@ const referenceConverter: TypeConverter<
             return ref;
         }
 
-        if (
-            context
-                .getComment(symbol, ReflectionKind.Interface)
-                ?.hasModifier("@inline")
-        ) {
+        let name: string;
+        if (ts.isIdentifier(node.typeName)) {
+            name = node.typeName.text;
+        } else {
+            name = node.typeName.right.text;
+        }
+
+        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
@@ -820,13 +820,6 @@ const referenceConverter: TypeConverter<
             );
         }
 
-        let name: string;
-        if (ts.isIdentifier(node.typeName)) {
-            name = node.typeName.text;
-        } else {
-            name = node.typeName.right.text;
-        }
-
         const ref = context.createSymbolReference(
             context.resolveAliasedSymbol(symbol),
             context,

src/lib/utils/options/tsdoc-defaults.ts

@@ -41,6 +41,8 @@ export const blockTags = [
     "@type",
     "@typedef",
     "@summary",
+    "@preventInline",
+    "@inlineType",
 ] as const;
 
 export const tsdocInlineTags = ["@link", "@inheritDoc", "@label"] as const;

src/test/behavior.c2.test.ts

@@ -1203,6 +1203,33 @@ describe("Behavior Tests", () => {
         );
     });
 
+    it("Handles the @preventInline tag preventing @inline from taking effect", () => {
+        const project = convert("inlineTag");
+
+        const bar2 = querySig(project, "bar2");
+        equal(
+            bar2.parameters?.map((p) => p.type?.toString()),
+            ["Record<string, Foo>"],
+        );
+
+        const baz = querySig(project, "Class.baz");
+        equal(
+            baz.parameters?.map((p) => p.type?.toString()),
+            ["Foo"],
+        );
+        equal(baz.type?.toString(), "Complex<number>");
+    });
+
+    it("Handles the @inlineType tag to inline a requested type", () => {
+        const project = convert("inlineTag");
+
+        const selectiveInline = querySig(project, "selectiveInline");
+        equal(
+            selectiveInline.parameters?.map((p) => p.type?.toString()),
+            ["{ inlined: false }"],
+        );
+    });
+
     it("Handles the @useDeclaredType tag on types", () => {
         const project = convert("useDeclaredTypeTag");
         const data = query(project, "Data");

src/test/converter2/behavior/inlineTag.ts

@@ -1,6 +1,8 @@
 /** @inline */
 type Foo = { inlined: true };
 
+type Bar = { inlined: false };
+
 /** @inline */
 type Complex<T> = { real: T; imag: T };
 
@@ -15,6 +17,10 @@ export function genericInline<T>(): Complex<T> {
 // TypeNode, nested
 export function bar(param: Record<string, Foo>) {}
 
+// TypeNode, prevented
+/** @preventInline Foo */
+export function bar2(param: Record<string, Foo>) {}
+
 export class Class {
     // Type * 2
     foo(param: Foo): Complex<number> {
@@ -23,4 +29,17 @@ export class Class {
 
     // Type, nested
     bar(param: Record<string, Foo>) {}
+
+    // Type * 2 - prevented
+    /**
+     * @preventInline Foo
+     * @preventInline Complex
+     */
+    baz(param: Foo): Complex<number> {
+        return { real: 1.0, imag: 2.0 };
+    }
+}
+
+/** @inlineType Bar */
+export function selectiveInline(bar: Bar) {
 }

tsdoc.json

@@ -116,6 +116,14 @@
             "tagName": "@inline",
             "syntaxKind": "modifier"
         },
+        {
+            "tagName": "@preventInline",
+            "syntaxKind": "block"
+        },
+        {
+            "tagName": "@inlineType",
+            "syntaxKind": "block"
+        },
         {
             "tagName": "@primaryExport",
             "syntaxKind": "modifier"