Include TOC & index on object type aliases

Resolves #2817

Author: Gerrit0

.config/typedoc.json

@@ -76,5 +76,8 @@
         "@types/markdown-it": {
             "MarkdownIt": "https://markdown-it.github.io/markdown-it/#MarkdownIt"
         }
-    }
+    },
+
+    // Saves a couple seconds when generating docs
+    "skipErrorChecking": true
 }

CHANGELOG.md

@@ -16,6 +16,8 @@ title: Changelog
 - Function-like variable exports will now only be automatically converted as function types if
   they are initialized with a function expression. TypeDoc can be instructed to convert them as functions
   with the `@function` tag, #2881.
+- Object literal type alias types will now be converted in a way which causes them to be rendered more similarly
+  to how interfaces are rendered, #2817.
 
 ### API Breaking Changes
 

src/lib/converter/plugins/MergeModuleWithPlugin.ts

@@ -72,6 +72,6 @@ export class MergeModuleWithPlugin extends ConverterComponent {
         this.application.logger.verbose(
             `Merging ${refl.getFullName()} into ${target.getFullName()}`,
         );
-        project.mergeModules(refl, target);
+        project.mergeReflections(refl, target);
     }
 }

src/lib/converter/symbols.ts

@@ -186,7 +186,10 @@ export function convertSymbol(
 ): void {
     // #1795, defer conversion of symbols named `default` so that if a function
     // is default exported and also exported with a name, the name takes precedence
-    if ((exportSymbol?.name ?? symbol.name) === "default") {
+    if (
+        (exportSymbol?.name ?? symbol.name) === "default" &&
+        context.scope.kindOf(ReflectionKind.ExportContainer)
+    ) {
         context.converter.deferConversion(() => {
             _convertSymbolNow(context, symbol, exportSymbol);
         });
@@ -357,6 +360,7 @@ function convertTypeAlias(
             symbol,
             exportSymbol,
         );
+        context.finalizeDeclarationReflection(reflection);
 
         if (reflection.comment?.hasModifier("@useDeclaredType")) {
             reflection.comment.removeModifier("@useDeclaredType");
@@ -373,12 +377,19 @@ function convertTypeAlias(
 
         if (reflection.type.type === "union") {
             attachUnionComments(context, declaration, reflection.type);
+        } else if (reflection.type.type === "reflection" && reflection.type.declaration.children) {
+            // #2817 lift properties of object literal types up to the reflection level.
+            const typeDecl = reflection.type.declaration;
+            reflection.project.mergeReflections(typeDecl, reflection);
+            delete reflection.type;
+
+            // When created any signatures will be created with __type as their
+            // name, rename them so that they have the alias's name as their name
+            for (const sig of reflection.signatures || []) {
+                sig.name = reflection.name;
+            }
         }
 
-        context.finalizeDeclarationReflection(reflection);
-
-        // Do this after finalization so that the CommentPlugin can get @typeParam tags
-        // from the parent comment. Ugly, but works for now. Should be cleaned up eventually.
         reflection.typeParameters = declaration.typeParameters?.map((param) =>
             createTypeParamReflection(param, context.withScope(reflection))
         );

src/lib/models/ContainerReflection.ts

@@ -1,11 +1,11 @@
 import { Reflection, type TraverseCallback, TraverseProperty } from "./Reflection.js";
 import { ReflectionCategory } from "./ReflectionCategory.js";
 import { ReflectionGroup } from "./ReflectionGroup.js";
-import type { ReflectionKind } from "./kind.js";
+import { ReflectionKind } from "./kind.js";
 import type { Deserializer, JSONOutput, Serializer } from "#serialization";
 import type { DocumentReflection } from "./DocumentReflection.js";
 import type { DeclarationReflection } from "./DeclarationReflection.js";
-import { removeIfPresent } from "#utils";
+import { assertNever, removeIfPresent } from "#utils";
 
 /**
  * @category Reflections
@@ -59,17 +59,39 @@ export abstract class ContainerReflection extends Reflection {
         return (this.children || []).filter((child) => child.kindOf(kind));
     }
 
-    addChild(child: DeclarationReflection | DocumentReflection) {
+    addChild(child: Reflection) {
         if (child.isDeclaration()) {
             this.children ||= [];
             this.children.push(child);
-        } else {
+
+            this.childrenIncludingDocuments ||= [];
+            this.childrenIncludingDocuments.push(child);
+        } else if (child.isDocument()) {
             this.documents ||= [];
             this.documents.push(child);
-        }
 
-        this.childrenIncludingDocuments ||= [];
-        this.childrenIncludingDocuments.push(child);
+            this.childrenIncludingDocuments ||= [];
+            this.childrenIncludingDocuments.push(child);
+        } else if (this.isDeclaration() && child.isSignature()) {
+            switch (child.kind) {
+                case ReflectionKind.CallSignature:
+                case ReflectionKind.ConstructorSignature:
+                    this.signatures ||= [];
+                    this.signatures.push(child);
+                    break;
+                case ReflectionKind.IndexSignature:
+                    this.indexSignatures ||= [];
+                    this.indexSignatures.push(child);
+                    break;
+                case ReflectionKind.GetSignature:
+                case ReflectionKind.SetSignature:
+                    throw new Error("Unsupported child type: " + ReflectionKind[child.kind]);
+                default:
+                    assertNever(child.kind);
+            }
+        } else {
+            throw new Error("Unsupported child type: " + ReflectionKind[child.kind]);
+        }
     }
 
     removeChild(child: DeclarationReflection | DocumentReflection) {

src/lib/models/ProjectReflection.ts

@@ -223,7 +223,7 @@ export class ProjectReflection extends ContainerReflection {
     }
 
     /** @internal */
-    mergeModules(
+    mergeReflections(
         source: DeclarationReflection,
         target: DeclarationReflection | ProjectReflection,
     ) {
@@ -234,9 +234,7 @@ export class ProjectReflection extends ContainerReflection {
         const newChildren = this.reflectionChildren.get(target.id);
 
         for (const childId of oldChildrenIds) {
-            const childRefl = this.getReflectionById(childId) as
-                | DocumentReflection
-                | DeclarationReflection;
+            const childRefl = this.getReflectionById(childId);
 
             // To avoid conflicting with some plugins which do this surgery somewhat incorrectly
             // (typedoc-plugin-merge-modules and likely others I'm not aware of) only move children

src/lib/output/formatter.tsx

@@ -836,6 +836,19 @@ export class FormattedCodeBuilder {
         return simpleElement(<span class="tsd-signature-symbol">{"{}"}</span>);
     }
 
+    typeAlias(item: DeclarationReflection) {
+        return nodes(
+            simpleElement(<span class="tsd-signature-keyword">type</span>),
+            space(),
+            simpleElement(<span class={getKindClass(item)}>{item.name}</span>),
+            this.typeParameters(item),
+            space(),
+            simpleElement(<span class="tsd-signature-symbol">{"="}</span>),
+            space(),
+            this.reflection(item, { topLevelLinks: true }),
+        );
+    }
+
     interface(item: DeclarationReflection) {
         return nodes(
             simpleElement(<span class="tsd-signature-keyword">interface</span>),

src/lib/output/themes/default/partials/reflectionPreview.tsx

@@ -18,4 +18,14 @@ export function reflectionPreview(context: DefaultThemeRenderContext, props: Ref
 
         return <div class="tsd-signature">{generator.toElement()}</div>;
     }
+
+    if (props.kindOf(ReflectionKind.TypeAlias) && props.children) {
+        const builder = new FormattedCodeBuilder(context.router, context.model);
+        const tree = builder.typeAlias(props);
+        const generator = new FormattedCodeGenerator(context.options.getValue("typePrintWidth"));
+        generator.forceWrap(builder.forceWrap); // Ensure elements are added to new lines.
+        generator.node(tree, Wrap.Enable);
+
+        return <div class="tsd-signature">{generator.toElement()}</div>;
+    }
 }

src/lib/output/themes/default/partials/typeDetails.tsx

@@ -323,8 +323,7 @@ function renderIndexSignature(context: DefaultThemeRenderContext, index: Signatu
                         {context.type(item.type)}
                     </>
                 ))}
-                <span class="tsd-signature-symbol">{"]: "}</span>
-                {context.type(index.type)}
+                <span class="tsd-signature-symbol">]:</span> {context.type(index.type)}
             </h5>
             {context.commentSummary(index)}
             {context.commentTags(index)}

src/lib/output/themes/default/templates/reflection.tsx

@@ -12,7 +12,8 @@ import { i18n, JSX } from "#utils";
 export function reflectionTemplate(context: DefaultThemeRenderContext, props: PageEvent<ContainerReflection>) {
     if (
         props.model.kindOf(ReflectionKind.TypeAlias | ReflectionKind.Variable) &&
-        props.model instanceof DeclarationReflection
+        props.model instanceof DeclarationReflection &&
+        props.model.type
     ) {
         return context.memberDeclaration(props.model);
     }
@@ -87,8 +88,7 @@ function renderIndexSignature(context: DefaultThemeRenderContext, index: Signatu
                         <span class={getKindClass(item)}>{item.name}</span>: {context.type(item.type)}
                     </>
                 ))}
-                <span class="tsd-signature-symbol">]:</span>
-                {context.type(index.type)}
+                <span class="tsd-signature-symbol">]:</span> {context.type(index.type)}
             </div>
             {context.commentSummary(index)}
             {context.commentTags(index)}

src/test/behavior.c2.test.ts

@@ -11,7 +11,7 @@ import {
 import { filterMap } from "#utils";
 import { CommentStyle } from "../lib/utils/options/declaration.js";
 import { TestLogger } from "./TestLogger.js";
-import { getComment, getSigComment, query, querySig } from "./utils.js";
+import { getComment, getSigComment, query, querySig, reflToTree } from "./utils.js";
 import { getConverter2App, getConverter2Project } from "./programs.js";
 
 type NameTree = { [name: string]: NameTree | undefined };
@@ -1402,4 +1402,19 @@ describe("Behavior Tests", () => {
         // Previously, would find TypeDoc's root readme
         equal(project.readme, undefined);
     });
+
+    it("Supports @document tags", () => {
+        const project = convert("documentTag");
+
+        equal(reflToTree(project), {
+            HasDescriptor: "Interface",
+        });
+
+        const refl = query(project, "HasDescriptor");
+        equal(refl.documents?.length, 1);
+
+        equal(refl.documents[0].content, [
+            { kind: "text", text: "External doc!" },
+        ]);
+    });
 });

src/test/converter.test.ts

@@ -14,9 +14,10 @@ import {
     ReflectionGroup,
     resetReflectionID,
     Serializer,
+    type SomeReflection,
     SourceReference,
 } from "../index.js";
-import type { ModelToObject, SomeReflection } from "../lib/serialization/schema.js";
+import type { ModelToObject } from "../lib/serialization/schema.js";
 import { getExpandedEntryPointsForPaths, normalizePath } from "../lib/utils/index.js";
 import { getConverterApp, getConverterBase, getConverterProgram } from "./programs.js";
 import { FileRegistry } from "../lib/models/FileRegistry.js";
@@ -76,8 +77,11 @@ comparisonSerializer.addSerializer<SomeReflection>({
     supports(x) {
         return x instanceof Reflection;
     },
-    toObject(_refl, obj) {
+    toObject(refl, obj: any) {
         delete obj["id"];
+        if (refl.isDeclaration()) {
+            obj["childrenIncludingDocuments"] = refl.childrenIncludingDocuments?.map(id => id.getFullName());
+        }
         return obj;
     },
 });

src/test/converter/comment/comment.ts

@@ -1,7 +1,9 @@
 /**
- * This is a module doc comment with legacy behavior.
+ * Module doc comment with document.
+ *
+ * @document document.md
+ * @packageDocumentation
  */
-/** dummy comment */
 import "./comment2";
 
 /**

src/test/converter/comment/document.md

@@ -0,0 +1 @@
+External doc included with `@document` tag!