Support for comments on type alias union members

Fixes #2585

Author: Gerrit0

CHANGELOG.md

@@ -43,6 +43,8 @@
     are currently shipped in the package, but it is now possible to add support for additional languages, #2475.
 -   Added support for a `packageOptions` object which specifies options that should be applied to each entry point when running with `--entryPointStrategy packages`, #2523.
 -   `--hostedBaseUrl` will now be used to generate a `<link rel="canonical">` element in the project root page, #2550.
+-   Added support for documenting individual elements of a union type, #2585.
+    Note: This feature is only available on type aliases directly containing unions.
 -   New option, `--customFooterHtml` to add custom HTML to the generated page footer, #2559.
 -   TypeDoc will now copy modifier tags to children if specified in the `--cascadedModifierTags` option, #2056.
 -   TypeDoc will now warn if mutually exclusive modifier tags are specified for a comment (e.g. both `@alpha` and `@beta`), #2056.
@@ -54,6 +56,8 @@
     If `--projectDocuments` is used to add documents, this option defaults to `true`, otherwise, defaults to `false`.
 -   Added new `--highlightLanguages` option to control what Shiki language packages are loaded.
 -   TypeDoc will now render union elements on new lines if there are more than 3 items in the union.
+-   TypeDoc will now only render the "Type Declaration" section if it will provide additional information not already presented in the page.
+    This results in significantly smaller documentation pages in many cases where that section would just repeat what has already been presented in the rendered type.
 
 ### Bug Fixes
 
@@ -68,6 +72,7 @@
 -   Fixed issue where search results could not be navigated while Windows Narrator was on, #2563.
 -   `charset` is now correctly cased in `<meta>` tag generated by the default theme, #2568.
 -   Fixed very slow conversion on Windows where Msys git was used by typedoc to discover repository links, #2586.
+-   The `--hideParameterTypesInTitle` option no longer applies when rendering function types.
 -   Fixed `externalSymbolLinkMappings` option's support for [meanings](https://typedoc.org/guides/declaration-references/#meaning) in declaration references.
 -   Buttons to copy code now have the `type=button` attribute set to avoid being treated as submit buttons.
 -   `--hostedBaseUrl` will now implicitly add a trailing slash to the generated URL.

scripts/capture_screenshots.mjs

@@ -84,12 +84,14 @@ function findHtmlPages(root) {
  * @param {string} outputDirectory
  * @param {number} jobs
  * @param {boolean} headless
+ * @param {string} theme
  */
 export async function captureScreenshots(
     baseDirectory,
     outputDirectory,
     jobs,
     headless,
+    theme,
 ) {
     const browser = await puppeteer.launch({
         args:
@@ -104,10 +106,9 @@ export async function captureScreenshots(
     console.log(`Processing ${pages.length} pages with ${jobs} workers`);
     for (const file of pages) {
         queue.add(async () => {
-            console.log("Starting", file);
             const outputPath = resolve(
                 outputDirectory,
-                relative(baseDirectory, file).replace(/\.html$/, ""),
+                relative(baseDirectory, file).replace(/\.html$/, ".png"),
             );
             fs.mkdirSync(dirname(outputPath), { recursive: true });
 
@@ -118,26 +119,16 @@ export async function captureScreenshots(
                 waitUntil: ["domcontentloaded"],
             });
 
-            await page.evaluate(() => {
-                document.documentElement.dataset.theme = "light";
-            });
-            await page.screenshot({
-                path: outputPath + "-light.png",
-                fullPage: true,
-            });
-            console.log("Captured light image for", file);
-
-            await page.evaluate(() => {
-                document.documentElement.dataset.theme = "dark";
-            });
+            await page.evaluate(
+                `document.documentElement.dataset.theme = "${theme}"`,
+            );
             await page.screenshot({
-                path: outputPath + "-dark.png",
+                path: outputPath,
                 fullPage: true,
             });
-            console.log("Captured dark image for", file);
 
             await context.close();
-            console.log("Finished", file);
+            console.log("Finished", relative(baseDirectory, file));
         });
     }
 
@@ -169,6 +160,10 @@ if (import.meta.url.endsWith(process.argv[1])) {
                 type: "boolean",
                 default: false,
             },
+            theme: {
+                type: "string",
+                default: "light",
+            },
         },
     });
 
@@ -178,6 +173,12 @@ if (import.meta.url.endsWith(process.argv[1])) {
 
     const start = Date.now();
     await fs.promises.rm(output, { recursive: true, force: true });
-    await captureScreenshots(docs, output, jobs, !args.values.debug);
+    await captureScreenshots(
+        docs,
+        output,
+        jobs,
+        !args.values.debug,
+        args.values.theme || "light",
+    );
     console.log(`Took ${(Date.now() - start) / 1000} seconds`);
 }

src/lib/converter/comments/index.ts

@@ -196,7 +196,7 @@ export function getComment(
 
 export function getNodeComment(
     node: ts.Node,
-    kind: ReflectionKind,
+    moduleComment: boolean,
     config: CommentParserConfig,
     logger: Logger,
     commentStyle: CommentStyle,
@@ -207,7 +207,7 @@ export function getNodeComment(
         discoverNodeComment(node, commentStyle),
         config,
         logger,
-        kind === ReflectionKind.Module,
+        moduleComment,
         checker,
         files,
     );

src/lib/converter/context.ts

@@ -294,10 +294,10 @@ export class Context {
         );
     }
 
-    getNodeComment(node: ts.Node, kind: ReflectionKind) {
+    getNodeComment(node: ts.Node, moduleComment: boolean) {
         return getNodeComment(
             node,
-            kind,
+            moduleComment,
             this.converter.config,
             this.logger,
             this.converter.commentStyle,

src/lib/converter/factories/index-signature.ts

@@ -26,7 +26,7 @@ export function convertIndexSignatures(context: Context, symbol: ts.Symbol) {
             ReflectionKind.IndexSignature,
             context.scope,
         );
-        index.comment = context.getNodeComment(indexDeclaration, index.kind);
+        index.comment = context.getNodeComment(indexDeclaration, false);
         index.parameters = [
             new ParameterReflection(
                 param.name.getText(),

src/lib/converter/symbols.ts

@@ -8,6 +8,7 @@ import {
     type Reflection,
     ReflectionFlag,
     ReflectionKind,
+    UnionType,
 } from "../models";
 import {
     getEnumFlags,
@@ -349,6 +350,10 @@ function convertTypeAlias(
             declaration.type,
         );
 
+        if (reflection.type.type === "union") {
+            attachUnionComments(context, declaration, reflection.type);
+        }
+
         context.finalizeDeclarationReflection(reflection);
 
         // Do this after finalization so that the CommentPlugin can get @typeParam tags
@@ -366,6 +371,40 @@ function convertTypeAlias(
     }
 }
 
+function attachUnionComments(
+    context: Context,
+    declaration: ts.TypeAliasDeclaration,
+    union: UnionType,
+) {
+    const list = declaration.type.getChildAt(0);
+    if (list.kind !== ts.SyntaxKind.SyntaxList) return;
+
+    let unionIndex = 0;
+    for (const child of list.getChildren()) {
+        const comment = context.getNodeComment(child, false);
+        if (comment?.modifierTags.size || comment?.blockTags.length) {
+            context.logger.warn(
+                context.logger.i18n.comment_for_0_should_not_contain_block_or_modifier_tags(
+                    context.scope.getFriendlyFullName() + "." + unionIndex,
+                ),
+                child,
+            );
+        }
+
+        if (comment) {
+            union.elementSummaries ||= Array.from(
+                { length: union.types.length },
+                () => [],
+            );
+            union.elementSummaries[unionIndex] = comment.summary;
+        }
+
+        if (child.kind !== ts.SyntaxKind.BarToken) {
+            ++unionIndex;
+        }
+    }
+}
+
 function convertTypeAliasAsInterface(
     context: Context,
     symbol: ts.Symbol,

src/lib/converter/types.ts

@@ -1067,6 +1067,7 @@ const unionConverter: TypeConverter<ts.UnionTypeNode, ts.UnionType> = {
     },
     convertType(context, type) {
         const types = type.types.map((type) => convertType(context, type));
+        normalizeUnion(types);
         sortLiteralUnion(types);
 
         return new UnionType(types);
@@ -1152,3 +1153,32 @@ function sortLiteralUnion(types: SomeType[]) {
         return (aLit.value as number) - (bLit.value as number);
     });
 }
+
+function normalizeUnion(types: SomeType[]) {
+    let trueIndex = -1;
+    let falseIndex = -1;
+    for (
+        let i = 0;
+        i < types.length && (trueIndex === -1 || falseIndex === -1);
+        i++
+    ) {
+        const t = types[i];
+        if (t instanceof LiteralType) {
+            if (t.value === true) {
+                trueIndex = i;
+            }
+            if (t.value === false) {
+                falseIndex = i;
+            }
+        }
+    }
+
+    if (trueIndex !== -1 && falseIndex !== -1) {
+        types.splice(Math.max(trueIndex, falseIndex), 1);
+        types.splice(
+            Math.min(trueIndex, falseIndex),
+            1,
+            new IntrinsicType("boolean"),
+        );
+    }
+}

src/lib/internationalization/translatable.ts

@@ -53,6 +53,8 @@ export const translatable = {
     converting_0_as_class_requires_value_declaration: `Converting {0} as a class requires a declaration which represents a non-type value.`,
     converting_0_as_class_without_construct_signatures: `{0} is being converted as a class, but does not have any construct signatures`,
 
+    comment_for_0_should_not_contain_block_or_modifier_tags: `The comment for {0} should not contain any block or modifier tags.`,
+
     symbol_0_has_multiple_declarations_with_comment: `{0} has multiple declarations with a comment. An arbitrary comment will be used.`,
     comments_for_0_are_declared_at_1: `The comments for {0} are declared at:\n\t{1}`,
 

src/lib/models/comments/comment.ts

@@ -8,11 +8,26 @@ import { NonEnumerable } from "../../utils/general";
 /**
  * Represents a parsed piece of a comment.
  * @category Comments
+ * @see {@link JSONOutput.CommentDisplayPart}
  */
 export type CommentDisplayPart =
+    /**
+     * Represents a plain text portion of the comment, may contain markdown
+     */
     | { kind: "text"; text: string }
+    /**
+     * Represents a code block separated out form the plain text entry so
+     * that TypeDoc knows to skip it when parsing relative links and inline tags.
+     **/
     | { kind: "code"; text: string }
+    /**
+     * Represents an inline tag like `{@link Foo}`
+     */
     | InlineTagDisplayPart
+    /**
+     * Represents a reference to a path relative to where the comment resides.
+     * This is used to detect and copy relative image links.
+     */
     | RelativeLinkDisplayPart;
 
 /**

src/lib/models/types.ts

@@ -9,6 +9,7 @@ import { ReflectionSymbolId } from "./reflections/ReflectionSymbolId";
 import type { DeclarationReference } from "../converter/comments/declarationReference";
 import { findPackageForPath } from "../utils/fs";
 import { ReflectionKind } from "./reflections/kind";
+import { Comment, CommentDisplayPart } from "./comments";
 
 /**
  * Base class of all type definitions.
@@ -1315,9 +1316,16 @@ export class TypeOperatorType extends Type {
 export class UnionType extends Type {
     override readonly type = "union";
 
+    /**
+     * If present, there should be as many items in this array as there are items in the {@link types} array.
+     *
+     * This member is only valid on unions which are on {@link DeclarationReflection.type | DeclarationReflection.type} with a
+     * {@link ReflectionKind} `kind` of `TypeAlias`. Specifying it on any other union is undefined behavior.
+     */
+    elementSummaries?: CommentDisplayPart[][];
+
     constructor(public types: SomeType[]) {
         super();
-        this.normalize();
     }
 
     protected override getTypeString(): string {
@@ -1356,31 +1364,10 @@ export class UnionType extends Type {
         return map[context];
     }
 
-    private normalize() {
-        let trueIndex = -1;
-        let falseIndex = -1;
-        for (
-            let i = 0;
-            i < this.types.length && (trueIndex === -1 || falseIndex === -1);
-            i++
-        ) {
-            const t = this.types[i];
-            if (t instanceof LiteralType) {
-                if (t.value === true) {
-                    trueIndex = i;
-                }
-                if (t.value === false) {
-                    falseIndex = i;
-                }
-            }
-        }
-
-        if (trueIndex !== -1 && falseIndex !== -1) {
-            this.types.splice(Math.max(trueIndex, falseIndex), 1);
-            this.types.splice(
-                Math.min(trueIndex, falseIndex),
-                1,
-                new IntrinsicType("boolean"),
+    override fromObject(de: Deserializer, obj: JSONOutput.UnionType): void {
+        if (obj.elementSummaries) {
+            this.elementSummaries = obj.elementSummaries.map((parts) =>
+                Comment.deserializeDisplayParts(de, parts),
             );
         }
     }
@@ -1389,6 +1376,9 @@ export class UnionType extends Type {
         return {
             type: this.type,
             types: this.types.map((t) => serializer.toObject(t)),
+            elementSummaries: this.elementSummaries?.map((parts) =>
+                Comment.serializeDisplayParts(serializer, parts),
+            ),
         };
     }
 }

src/lib/output/models/UrlMapping.ts

@@ -19,4 +19,8 @@ export class UrlMapping<Model = any> {
     }
 }
 
+/**
+ * @param data the reflection to render
+ * @returns either a string to be written to the file, or an element to be serialized and then written.
+ */
 export type RenderTemplate<T> = (data: T) => JSX.Element | string;