typedoc 0.26.0-beta.1 → 0.26.0-beta.3

package/dist/lib/converter/comments/textParser.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textContent = textContent;
+const html_1 = require("../../utils/html");
+const lexer_1 = require("./lexer");
+const markdown_it_1 = __importDefault(require("markdown-it"));
+const MdHelpers = new markdown_it_1.default().helpers;
+/**
+ * Look for relative links within a piece of text and add them to the {@link FileRegistry}
+ * so that they can be correctly resolved during rendering.
+ */
+function textContent(sourcePath, token, i18n, warning, outContent, files, atNewLine) {
+    let lastPartEnd = 0;
+    const data = {
+        sourcePath,
+        token,
+        pos: 0,
+        i18n,
+        warning,
+        files: files,
+        atNewLine,
+    };
+    function addRef(ref) {
+        outContent.push({
+            kind: "text",
+            text: token.text.slice(lastPartEnd, ref.pos),
+        });
+        outContent.push({
+            kind: "relative-link",
+            text: token.text.slice(ref.pos, ref.end),
+            target: ref.target,
+        });
+        lastPartEnd = ref.end;
+        data.pos = ref.end;
+        if (!ref.target) {
+            warning(i18n.relative_path_0_does_not_exist(token.text.slice(ref.pos, ref.end)), {
+                kind: lexer_1.TokenSyntaxKind.Text,
+                pos: ref.pos,
+                text: token.text.slice(ref.pos, ref.end),
+            });
+        }
+    }
+    while (data.pos < token.text.length) {
+        const link = checkMarkdownLink(data);
+        if (link) {
+            addRef(link);
+            continue;
+        }
+        const reference = checkReference(data);
+        if (reference) {
+            addRef(reference);
+            continue;
+        }
+        const tagLink = checkTagLink(data);
+        if (tagLink) {
+            addRef(tagLink);
+            continue;
+        }
+        ++data.pos;
+    }
+    if (lastPartEnd !== token.text.length) {
+        outContent.push({ kind: "text", text: token.text.slice(lastPartEnd) });
+    }
+}
+/**
+ * Links are inline text with the form `[ text ]( url title )`.
+ *
+ * Images are just links with a leading `!` and lack of support for `[ref]` referring to a path
+ * defined elsewhere, we don't care about that distinction here as we'll only replace the path
+ * piece of the image.
+ *
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_inline/link.mjs
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_inline/image.mjs
+ *
+ */
+function checkMarkdownLink(data) {
+    const { token, sourcePath, files } = data;
+    if (token.text[data.pos] === "[") {
+        const labelEnd = findLabelEnd(token.text, data.pos + 1);
+        if (labelEnd !== -1 &&
+            token.text[labelEnd] === "]" &&
+            token.text[labelEnd + 1] === "(") {
+            const link = MdHelpers.parseLinkDestination(token.text, labelEnd + 2, token.text.length);
+            if (link.ok) {
+                // Only make a relative-link display part if it's actually a relative link.
+                // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
+                if (isRelativeLink(link.str)) {
+                    return {
+                        pos: labelEnd + 2,
+                        end: link.pos,
+                        target: files.register(sourcePath, link.str),
+                    };
+                }
+                // This was a link, skip ahead to ensure we don't happen to parse
+                // something else as a link within the link.
+                data.pos = link.pos - 1;
+            }
+        }
+    }
+}
+/**
+ * Reference definitions are blocks with the form `[label]: link title`
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_block/reference.mjs
+ *
+ * Note: This may include false positives where TypeDoc recognizes a reference block that markdown
+ * does not if users start lines with something that looks like a reference block without fully
+ * separating it from an above paragraph. For a first cut, this is good enough.
+ */
+function checkReference(data) {
+    const { atNewLine, pos, token, files, sourcePath } = data;
+    if (atNewLine) {
+        let lookahead = pos;
+        while (/[ \t]/.test(token.text[lookahead])) {
+            ++lookahead;
+        }
+        if (token.text[lookahead] === "[") {
+            while (lookahead < token.text.length &&
+                /[^\n\]]/.test(token.text[lookahead])) {
+                ++lookahead;
+            }
+            if (token.text.startsWith("]:", lookahead)) {
+                lookahead += 2;
+                while (/[ \t]/.test(token.text[lookahead])) {
+                    ++lookahead;
+                }
+                const link = MdHelpers.parseLinkDestination(token.text, lookahead, token.text.length);
+                if (link.ok) {
+                    if (isRelativeLink(link.str)) {
+                        return {
+                            pos: lookahead,
+                            end: link.pos,
+                            target: files.register(sourcePath, link.str),
+                        };
+                    }
+                    data.pos = link.pos - 1;
+                }
+            }
+        }
+    }
+}
+/**
+ * Looks for `<a href="./relative">` and `<img src="./relative">`
+ */
+function checkTagLink(data) {
+    const { pos, token } = data;
+    if (token.text.startsWith("<img ", pos)) {
+        data.pos += 4;
+        return checkAttribute(data, "src");
+    }
+    if (token.text.startsWith("<a ", pos)) {
+        data.pos += 3;
+        return checkAttribute(data, "href");
+    }
+}
+function checkAttribute(data, attr) {
+    const parser = new html_1.HtmlAttributeParser(data.token.text, data.pos);
+    while (parser.state !== html_1.ParserState.END) {
+        if (parser.state === html_1.ParserState.BeforeAttributeValue &&
+            parser.currentAttributeName === attr) {
+            parser.step();
+            if (isRelativeLink(parser.currentAttributeValue)) {
+                data.pos = parser.pos;
+                return {
+                    pos: parser.currentAttributeValueStart,
+                    end: parser.currentAttributeValueEnd,
+                    target: data.files.register(data.sourcePath, parser.currentAttributeValue),
+                };
+            }
+            return;
+        }
+        parser.step();
+    }
+}
+function isRelativeLink(link) {
+    return !/^[a-z]+:\/\/|^\/|^[a-z]:\\/i.test(link);
+}
+function findLabelEnd(text, pos) {
+    while (pos < text.length) {
+        switch (text[pos]) {
+            case "\n":
+            case "]":
+                return pos;
+        }
+        ++pos;
+    }
+    return -1;
+}

package/dist/lib/converter/context.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { type Reflection, type ProjectReflection, DeclarationReflection, ReflectionKind, type DocumentReflection } from "../models/index";
+import { type Reflection, type ProjectReflection, DeclarationReflection, type DocumentReflection, ReflectionKind } from "../models/index";
 import type { Converter } from "./converter";
 import type { TranslationProxy } from "../internationalization/internationalization";
 /**
@@ -84,7 +84,7 @@ export declare class Context {
     /** @internal */
     setActiveProgram(program: ts.Program | undefined): void;
     getComment(symbol: ts.Symbol, kind: ReflectionKind): import("../models/index").Comment | undefined;
-    getNodeComment(node: ts.Node, kind: ReflectionKind): import("../models/index").Comment | undefined;
+    getNodeComment(node: ts.Node, moduleComment: boolean): import("../models/index").Comment | undefined;
     getFileComment(node: ts.SourceFile): import("../models/index").Comment | undefined;
     getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag): import("../models/index").Comment | undefined;
     getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): import("../models/index").Comment | undefined;

package/dist/lib/converter/context.js

@@ -72,9 +72,11 @@ class Context {
         if (!nodeType) {
             if (node.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.symbol);
+                // The TS types lie due to ts.SourceFile
             }
             else if (node.parent?.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.symbol);
+                // The TS types lie due to ts.SourceFile
             }
             else if (node.parent?.parent?.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.parent.symbol);
@@ -138,7 +140,10 @@ class Context {
         if (exportSymbol) {
             this.registerReflection(reflection, exportSymbol);
         }
-        this.registerReflection(reflection, symbol);
+        const path = reflection.kindOf(index_1.ReflectionKind.Namespace | index_1.ReflectionKind.Module)
+            ? symbol?.declarations?.find(typescript_1.default.isSourceFile)?.fileName
+            : undefined;
+        this.project.registerReflection(reflection, symbol, path);
     }
     finalizeDeclarationReflection(reflection) {
         this.converter.trigger(converter_events_1.ConverterEvents.CREATE_DECLARATION, this, reflection);
@@ -162,7 +167,7 @@ class Context {
      * @param symbol  The symbol the given reflection was resolved from.
      */
     registerReflection(reflection, symbol) {
-        this.project.registerReflection(reflection, symbol);
+        this.project.registerReflection(reflection, symbol, void 0);
     }
     /**
      * Trigger a node reflection event.
@@ -181,19 +186,19 @@ class Context {
         this._program = program;
     }
     getComment(symbol, kind) {
-        return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
+        return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
-    getNodeComment(node, kind) {
-        return (0, comments_1.getNodeComment)(node, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
+    getNodeComment(node, moduleComment) {
+        return (0, comments_1.getNodeComment)(node, moduleComment, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
     getFileComment(node) {
-        return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
+        return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
     getJsDocComment(declaration) {
-        return (0, comments_1.getJsDocComment)(declaration, this.converter.config, this.logger, this.converter.useTsLinkResolution ? this.checker : undefined);
+        return (0, comments_1.getJsDocComment)(declaration, this.converter.config, this.logger, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
     getSignatureComment(declaration) {
-        return (0, comments_1.getSignatureComment)(declaration, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined);
+        return (0, comments_1.getSignatureComment)(declaration, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
     withScope(scope) {
         const context = new Context(this.converter, this.programs, this.project, scope);

package/dist/lib/converter/converter.d.ts

@@ -9,7 +9,8 @@ import type { DocumentationEntryPoint } from "../utils/entry-point";
 import type { CommentParserConfig } from "./comments";
 import type { CommentStyle, ValidationOptions } from "../utils/options/declaration";
 import { type ExternalSymbolResolver, type ExternalResolveResult } from "./comments/linkResolver";
-import type { DeclarationReference } from "./comments/declarationReference";
+import { type DeclarationReference } from "./comments/declarationReference";
+import type { FileRegistry } from "../models/FileRegistry";
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
@@ -128,7 +129,7 @@ export declare class Converter extends ChildableComponent<Application, Converter
     /**
      * Parse the given file into a comment. Intended to be used with markdown files.
      */
-    parseRawComment(file: MinimalSourceFile): {
+    parseRawComment(file: MinimalSourceFile, files: FileRegistry): {
         content: CommentDisplayPart[];
         frontmatter: Record<string, unknown>;
     };
@@ -176,5 +177,6 @@ export declare class Converter extends ChildableComponent<Application, Converter
     /** @internal */
     isExternal(symbol: ts.Symbol): boolean;
     processDocumentTags(reflection: Reflection, parent: ContainerReflection): void;
+    private addDocument;
     private _buildCommentParserConfig;
 }

package/dist/lib/converter/converter.js

@@ -67,6 +67,7 @@ const enum_1 = require("../utils/enum");
 const parser_1 = require("./comments/parser");
 const rawLexer_1 = require("./comments/rawLexer");
 const linkResolver_1 = require("./comments/linkResolver");
+const declarationReference_1 = require("./comments/declarationReference");
 const path_1 = require("path");
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
@@ -190,7 +191,7 @@ let Converter = (() => {
                     name += ref.symbolReference.path.map((p) => p.path).join(".");
                 }
                 if (ref.symbolReference.meaning) {
-                    name += ":" + ref.symbolReference.meaning;
+                    name += (0, declarationReference_1.meaningToString)(ref.symbolReference.meaning);
                 }
                 if (typeof modLinks[name] === "string") {
                     return modLinks[name];
@@ -206,7 +207,7 @@ let Converter = (() => {
         convert(entryPoints) {
             const programs = (0, utils_1.unique)(entryPoints.map((e) => e.program));
             this.externalPatternCache = void 0;
-            const project = new index_1.ProjectReflection(this.application.options.getValue("name"));
+            const project = new index_1.ProjectReflection(this.application.options.getValue("name"), this.application.files);
             const context = new context_1.Context(this, programs, project);
             this.trigger(Converter.EVENT_BEGIN, context);
             this.addProjectDocuments(project);
@@ -220,11 +221,15 @@ let Converter = (() => {
         addProjectDocuments(project) {
             const projectDocuments = (0, utils_1.getDocumentEntryPoints)(this.application.logger, this.application.options);
             for (const { displayName, path } of projectDocuments) {
-                const file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
-                const { content, frontmatter } = this.parseRawComment(file);
-                const docRefl = new index_1.DocumentReflection(displayName, project, content, frontmatter);
-                project.addChild(docRefl);
-                project.registerReflection(docRefl);
+                let file;
+                try {
+                    file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
+                }
+                catch (error) {
+                    this.application.logger.error(this.application.logger.i18n.failed_to_read_0_when_processing_project_document(path));
+                    continue;
+                }
+                this.addDocument(project, file, displayName);
             }
         }
         /** @internal */
@@ -244,8 +249,8 @@ let Converter = (() => {
         /**
          * Parse the given file into a comment. Intended to be used with markdown files.
          */
-        parseRawComment(file) {
-            return (0, parser_1.parseCommentString)((0, rawLexer_1.lexCommentString)(file.text), this.config, file, this.application.logger);
+        parseRawComment(file, files) {
+            return (0, parser_1.parseCommentString)((0, rawLexer_1.lexCommentString)(file.text), this.config, file, this.application.logger, files);
         }
         /**
          * Adds a new resolver that the theme can use to try to figure out how to link to a symbol declared
@@ -319,7 +324,7 @@ let Converter = (() => {
             if (createModuleReflections === false) {
                 // Special case for when we're giving a single entry point, we don't need to
                 // create modules for each entry. Register the project as this module.
-                context.project.registerReflection(context.project, symbol);
+                context.project.registerReflection(context.project, symbol, entryPoint.sourceFile.fileName);
                 context.project.comment = symbol
                     ? context.getComment(symbol, context.project.kind)
                     : context.getFileComment(node);
@@ -334,7 +339,7 @@ let Converter = (() => {
                 }
                 if (entryPoint.readmeFile) {
                     const readme = (0, utils_1.readFile)(entryPoint.readmeFile);
-                    const { content } = this.parseRawComment(new utils_1.MinimalSourceFile(readme, entryPoint.readmeFile));
+                    const { content } = this.parseRawComment(new utils_1.MinimalSourceFile(readme, entryPoint.readmeFile), context.project.files);
                     reflection.readme = content;
                 }
                 reflection.packageVersion = entryPoint.version;
@@ -406,11 +411,56 @@ let Converter = (() => {
                         this.application.logger.warn(this.application.logger.i18n.failed_to_read_0_when_processing_document_tag_in_1((0, paths_1.nicePath)(path), (0, paths_1.nicePath)(reflection.comment.sourcePath)));
                         continue;
                     }
-                    const { content, frontmatter } = this.parseRawComment(file);
-                    const docRefl = new index_1.DocumentReflection((0, path_1.basename)(file.fileName).replace(/\.[^.]+$/, ""), parent, content, frontmatter);
-                    parent.addChild(docRefl);
-                    parent.project.registerReflection(docRefl);
+                    this.addDocument(parent, file, (0, path_1.basename)(file.fileName).replace(/\.[^.]+$/, ""));
+                }
+            }
+        }
+        addDocument(parent, file, displayName) {
+            const { content, frontmatter } = this.parseRawComment(file, parent.project.files);
+            const children = frontmatter["children"];
+            delete frontmatter["children"];
+            const docRefl = new index_1.DocumentReflection(displayName, parent, content, frontmatter);
+            parent.addChild(docRefl);
+            parent.project.registerReflection(docRefl, undefined, file.fileName);
+            const childrenToAdd = [];
+            if (children && typeof children === "object") {
+                if (Array.isArray(children)) {
+                    for (const child of children) {
+                        if (typeof child === "string") {
+                            childrenToAdd.push([
+                                (0, path_1.basename)(child).replace(/\.[^.]+$/, ""),
+                                child,
+                            ]);
+                        }
+                        else {
+                            this.application.logger.error(this.application.i18n.frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values((0, paths_1.nicePath)(file.fileName)));
+                            return;
+                        }
+                    }
+                }
+                else {
+                    for (const [name, path] of Object.entries(children)) {
+                        if (typeof path === "string") {
+                            childrenToAdd.push([name, path]);
+                        }
+                        else {
+                            this.application.logger.error(this.application.i18n.frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values((0, paths_1.nicePath)(file.fileName)));
+                            return;
+                        }
+                    }
+                }
+            }
+            for (const [displayName, path] of childrenToAdd) {
+                const absPath = (0, path_1.resolve)((0, path_1.dirname)(file.fileName), path);
+                let childFile;
+                try {
+                    childFile = new utils_1.MinimalSourceFile((0, utils_1.readFile)(absPath), absPath);
+                }
+                catch (error) {
+                    this.application.logger.error(this.application.logger.i18n.failed_to_read_0_when_processing_document_child_in_1(path, (0, paths_1.nicePath)(file.fileName)));
+                    continue;
                 }
+                this.addDocument(docRefl, childFile, displayName);
             }
         }
         _buildCommentParserConfig() {

package/dist/lib/converter/factories/index-signature.js

@@ -18,7 +18,7 @@ function convertIndexSignatures(context, symbol) {
         const param = indexDeclaration.parameters[0];
         (0, assert_1.default)(param && typescript_1.default.isParameter(param));
         const index = new models_1.SignatureReflection("__index", models_1.ReflectionKind.IndexSignature, context.scope);
-        index.comment = context.getNodeComment(indexDeclaration, index.kind);
+        index.comment = context.getNodeComment(indexDeclaration, false);
         index.parameters = [
             new models_1.ParameterReflection(param.name.getText(), models_1.ReflectionKind.Parameter, index),
         ];

package/dist/lib/converter/plugins/CategoryPlugin.js

@@ -114,9 +114,7 @@ let CategoryPlugin = (() => {
             if (this.defaultCategory) {
                 CategoryPlugin.defaultCategory = this.defaultCategory;
             }
-            if (this.categoryOrder) {
-                CategoryPlugin.WEIGHTS = this.categoryOrder;
-            }
+            CategoryPlugin.WEIGHTS = this.categoryOrder;
         }
         /**
          * Triggered when the converter has finished resolving a project.
@@ -157,7 +155,7 @@ let CategoryPlugin = (() => {
                 if (group.categories)
                     return;
                 group.categories = this.getReflectionCategories(obj, group.children);
-                if (group.categories && group.categories.length > 1) {
+                if (group.categories.length > 1) {
                     group.categories.sort(CategoryPlugin.sortCatCallback);
                 }
                 else if (group.categories.length === 1 &&
@@ -172,7 +170,7 @@ let CategoryPlugin = (() => {
                 return;
             }
             obj.categories = this.getReflectionCategories(obj, obj.childrenIncludingDocuments);
-            if (obj.categories && obj.categories.length > 1) {
+            if (obj.categories.length > 1) {
                 obj.categories.sort(CategoryPlugin.sortCatCallback);
             }
             else if (obj.categories.length === 1 &&

package/dist/lib/converter/plugins/CommentPlugin.js

@@ -76,6 +76,7 @@ const NEVER_RENDERED = [
     "@this",
     "@type",
     "@typedef",
+    "@jsx",
 ];
 // We might make this user configurable at some point, but for now,
 // this set is configured here.
@@ -397,6 +398,12 @@ let CommentPlugin = (() => {
                 }
                 mergeSeeTags(reflection.comment);
                 movePropertyTags(reflection.comment, reflection);
+                // Unlike other modifiers, this one has to wait until resolution to be removed
+                // as it needs to remain present so that it can be checked when `@hidden` tags are
+                // being processed.
+                if (reflection.kindOf(models_1.ReflectionKind.Class)) {
+                    reflection.comment.removeModifier("@hideconstructor");
+                }
             }
             if (reflection instanceof models_1.DeclarationReflection && reflection.comment) {
                 let sigs;
@@ -506,6 +513,19 @@ let CommentPlugin = (() => {
             if (this.excludedByCategory(reflection)) {
                 return true;
             }
+            if (reflection.kindOf(models_1.ReflectionKind.ConstructorSignature |
+                models_1.ReflectionKind.Constructor)) {
+                if (comment?.hasModifier("@hideconstructor"))
+                    return true;
+                const cls = reflection.parent?.kindOf(models_1.ReflectionKind.Class)
+                    ? reflection.parent
+                    : reflection.parent?.parent?.kindOf(models_1.ReflectionKind.Class)
+                        ? reflection.parent.parent
+                        : undefined;
+                if (cls?.comment?.hasModifier("@hideconstructor")) {
+                    return true;
+                }
+            }
             if (!comment) {
                 // We haven't moved comments from the parent for signatures without a direct
                 // comment, so don't exclude those due to not being documented.

package/dist/lib/converter/plugins/PackagePlugin.js

@@ -185,7 +185,7 @@ let PackagePlugin = (() => {
         }
         addEntries(project) {
             if (this.readmeFile && this.readmeContents) {
-                const { content } = this.application.converter.parseRawComment(new minimalSourceFile_1.MinimalSourceFile(this.readmeContents, this.readmeFile));
+                const { content } = this.application.converter.parseRawComment(new minimalSourceFile_1.MinimalSourceFile(this.readmeContents, this.readmeFile), project.files);
                 project.readme = content;
             }
             if (this.packageJson) {

package/dist/lib/converter/symbols.js

@@ -184,7 +184,7 @@ function convertNamespace(context, symbol, exportSymbol) {
 }
 function convertTypeAlias(context, symbol, exportSymbol) {
     const declaration = symbol
-        ?.getDeclarations()
+        .getDeclarations()
         ?.find((d) => typescript_1.default.isTypeAliasDeclaration(d) ||
         typescript_1.default.isJSDocTypedefTag(d) ||
         typescript_1.default.isJSDocCallbackTag(d) ||
@@ -198,6 +198,9 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         }
         const reflection = context.createDeclarationReflection(models_1.ReflectionKind.TypeAlias, symbol, exportSymbol);
         reflection.type = context.converter.convertType(context.withScope(reflection), 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
         // from the parent comment. Ugly, but works for now. Should be cleaned up eventually.
@@ -211,6 +214,25 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         (0, jsdoc_1.convertJsDocCallback)(context, symbol, declaration, exportSymbol);
     }
 }
+function attachUnionComments(context, declaration, union) {
+    const list = declaration.type.getChildAt(0);
+    if (list.kind !== typescript_1.default.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 !== typescript_1.default.SyntaxKind.BarToken) {
+            ++unionIndex;
+        }
+    }
+}
 function convertTypeAliasAsInterface(context, symbol, exportSymbol, declaration) {
     const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Interface, symbol, exportSymbol);
     context.finalizeDeclarationReflection(reflection);
@@ -322,7 +344,7 @@ function convertClassOrInterface(context, symbol, exportSymbol) {
         }
         reflectionContext.shouldBeStatic = false;
         const ctors = staticType.getConstructSignatures();
-        const constructMember = reflectionContext.createDeclarationReflection(models_1.ReflectionKind.Constructor, ctors?.[0]?.declaration?.symbol, void 0, "constructor");
+        const constructMember = reflectionContext.createDeclarationReflection(models_1.ReflectionKind.Constructor, ctors[0]?.declaration?.symbol, void 0, "constructor");
         // Modifiers are the same for all constructors
         if (ctors.length && ctors[0].declaration) {
             setModifiers(symbol, ctors[0].declaration, constructMember);
@@ -338,7 +360,7 @@ function convertClassOrInterface(context, symbol, exportSymbol) {
     // And type arguments
     if (instanceType.typeParameters) {
         reflection.typeParameters = instanceType.typeParameters.map((param) => {
-            const declaration = param.symbol?.declarations?.[0];
+            const declaration = param.symbol.declarations?.[0];
             (0, assert_1.default)(declaration && typescript_1.default.isTypeParameterDeclaration(declaration));
             return (0, signature_1.createTypeParamReflection)(declaration, reflectionContext);
         });
@@ -537,9 +559,7 @@ function convertVariableAsNamespace(context, symbol, exportSymbol) {
     const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Namespace, symbol, exportSymbol);
     context.finalizeDeclarationReflection(reflection);
     const rc = context.withScope(reflection);
-    const declaration = symbol.declarations?.find(typescript_1.default.isVariableDeclaration);
-    (0, assert_1.default)(declaration, "Missing variable declaration");
-    const type = context.checker.getTypeAtLocation(declaration);
+    const type = context.checker.getTypeOfSymbol(symbol);
     convertSymbols(rc, type.getProperties());
     return typescript_1.default.SymbolFlags.Property;
 }
@@ -600,7 +620,7 @@ function convertSymbolAsClass(context, symbol, exportSymbol) {
     rc.shouldBeStatic = false;
     const ctors = type.getConstructSignatures();
     if (ctors.length) {
-        const constructMember = rc.createDeclarationReflection(models_1.ReflectionKind.Constructor, ctors?.[0]?.declaration?.symbol, void 0, "constructor");
+        const constructMember = rc.createDeclarationReflection(models_1.ReflectionKind.Constructor, ctors[0]?.declaration?.symbol, void 0, "constructor");
         // Modifiers are the same for all constructors
         if (ctors.length && ctors[0].declaration) {
             setModifiers(symbol, ctors[0].declaration, constructMember);