typedoc 0.25.13 → 0.26.0-beta.0

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

@@ -1,7 +1,32 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseComment = void 0;
-const assert_1 = require("assert");
+exports.parseComment = parseComment;
+exports.parseCommentString = parseCommentString;
+const assert_1 = __importStar(require("assert"));
+const yaml_1 = require("yaml");
 const models_1 = require("../../models");
 const utils_1 = require("../../utils");
 const paths_1 = require("../../utils/paths");
@@ -43,20 +68,97 @@ function parseComment(tokens, config, file, logger) {
     const lexer = makeLookaheadGenerator(tokens);
     const tok = lexer.done() || lexer.peek();
     const comment = new models_1.Comment();
-    comment.summary = blockContent(comment, lexer, config, warningImpl);
+    comment.sourcePath = file.fileName;
+    comment.summary = blockContent(comment, lexer, config, logger.i18n, warningImpl);
     while (!lexer.done()) {
-        comment.blockTags.push(blockTag(comment, lexer, config, warningImpl));
+        comment.blockTags.push(blockTag(comment, lexer, config, logger.i18n, warningImpl));
     }
-    postProcessComment(comment, (message) => {
-        (0, assert_1.ok)(typeof tok === "object");
-        logger.warn(`${message} in comment at ${(0, paths_1.nicePath)(file.fileName)}:${file.getLineAndCharacterOfPosition(tok.pos).line + 1}`);
-    });
+    const tok2 = tok;
+    postProcessComment(comment, logger.i18n, () => `${(0, paths_1.nicePath)(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`, (message) => logger.warn(message));
     return comment;
     function warningImpl(message, token) {
         logger.warn(message, token.pos, file);
     }
 }
-exports.parseComment = parseComment;
+/**
+ * Intended for parsing markdown documents. This only parses code blocks and
+ * inline tags outside of code blocks, everything else is text.
+ *
+ * If you change this, also look at blockContent, as it likely needs similar
+ * modifications to ensure parsing is consistent.
+ */
+function parseCommentString(tokens, config, file, logger) {
+    const suppressWarningsConfig = {
+        ...config,
+        jsDocCompatibility: {
+            defaultTag: true,
+            exampleTag: true,
+            ignoreUnescapedBraces: true,
+            inheritDocTag: true,
+        },
+    };
+    const content = [];
+    const lexer = makeLookaheadGenerator(tokens);
+    while (!lexer.done()) {
+        let consume = true;
+        const next = lexer.peek();
+        switch (next.kind) {
+            case lexer_1.TokenSyntaxKind.TypeAnnotation:
+                // Shouldn't have been produced by our lexer
+                (0, assert_1.default)(false, "Should be unreachable");
+                break;
+            case lexer_1.TokenSyntaxKind.NewLine:
+            case lexer_1.TokenSyntaxKind.Text:
+            case lexer_1.TokenSyntaxKind.Tag:
+            case lexer_1.TokenSyntaxKind.CloseBrace:
+                content.push({ kind: "text", text: next.text });
+                break;
+            case lexer_1.TokenSyntaxKind.Code:
+                content.push({ kind: "code", text: next.text });
+                break;
+            case lexer_1.TokenSyntaxKind.OpenBrace:
+                inlineTag(lexer, content, suppressWarningsConfig, logger.i18n, (message, token) => logger.warn(message, token.pos, file));
+                consume = false;
+                break;
+            default:
+                (0, utils_1.assertNever)(next.kind);
+        }
+        if (consume) {
+            lexer.take();
+        }
+    }
+    // Check for frontmatter
+    let frontmatterData = {};
+    const firstBlock = content[0];
+    if (firstBlock.text.startsWith("---\n")) {
+        const end = firstBlock.text.indexOf("\n---\n");
+        if (end !== -1) {
+            const yamlText = firstBlock.text.slice("---\n".length, end);
+            firstBlock.text = firstBlock.text
+                .slice(end + "\n---\n".length)
+                .trimStart();
+            const frontmatter = (0, yaml_1.parseDocument)(yamlText, { prettyErrors: false });
+            for (const warning of frontmatter.warnings) {
+                // Can't translate issues coming from external library...
+                logger.warn(warning.message, warning.pos[0] + "---\n".length, file);
+            }
+            for (const error of frontmatter.errors) {
+                // Can't translate issues coming from external library...
+                logger.error(error.message, error.pos[0] + "---\n".length, file);
+            }
+            if (frontmatter.errors.length === 0) {
+                const data = frontmatter.toJS();
+                if (typeof data === "object") {
+                    frontmatterData = data;
+                }
+                else {
+                    logger.error(logger.i18n.yaml_frontmatter_not_an_object(), 5, file);
+                }
+            }
+        }
+    }
+    return { content, frontmatter: frontmatterData };
+}
 const HAS_USER_IDENTIFIER = [
     "@callback",
     "@param",
@@ -74,7 +176,7 @@ function makeCodeBlock(text) {
  * Loop over comment, produce lint warnings, and set tag names for tags
  * which have them.
  */
-function postProcessComment(comment, warning) {
+function postProcessComment(comment, i18n, getPosition, warning) {
     for (const tag of comment.blockTags) {
         if (HAS_USER_IDENTIFIER.includes(tag.tag) && tag.content.length) {
             const first = tag.content[0];
@@ -91,50 +193,50 @@ function postProcessComment(comment, warning) {
             }
         }
         if (tag.content.some((part) => part.kind === "inline-tag" && part.tag === "@inheritDoc")) {
-            warning("An inline @inheritDoc tag should not appear within a block tag as it will not be processed");
+            warning(i18n.inline_inheritdoc_should_not_appear_in_block_tag_in_comment_at_0(getPosition()));
         }
     }
     const remarks = comment.blockTags.filter((tag) => tag.tag === "@remarks");
     if (remarks.length > 1) {
-        warning("At most one @remarks tag is expected in a comment, ignoring all but the first");
+        warning(i18n.at_most_one_remarks_tag_expected_in_comment_at_0(getPosition()));
         (0, utils_1.removeIf)(comment.blockTags, (tag) => remarks.indexOf(tag) > 0);
     }
     const returns = comment.blockTags.filter((tag) => tag.tag === "@returns");
     if (remarks.length > 1) {
-        warning("At most one @returns tag is expected in a comment, ignoring all but the first");
+        warning(i18n.at_most_one_returns_tag_expected_in_comment_at_0(getPosition()));
         (0, utils_1.removeIf)(comment.blockTags, (tag) => returns.indexOf(tag) > 0);
     }
     const inheritDoc = comment.blockTags.filter((tag) => tag.tag === "@inheritDoc");
     const inlineInheritDoc = comment.summary.filter((part) => part.kind === "inline-tag" && part.tag === "@inheritDoc");
     if (inlineInheritDoc.length + inheritDoc.length > 1) {
-        warning("At most one @inheritDoc tag is expected in a comment, ignoring all but the first");
+        warning(i18n.at_most_one_inheritdoc_tag_expected_in_comment_at_0(getPosition()));
         const allInheritTags = [...inlineInheritDoc, ...inheritDoc];
         (0, utils_1.removeIf)(comment.summary, (part) => allInheritTags.indexOf(part) > 0);
         (0, utils_1.removeIf)(comment.blockTags, (tag) => allInheritTags.indexOf(tag) > 0);
     }
     if ((inlineInheritDoc.length || inheritDoc.length) &&
         comment.summary.some((part) => part.kind !== "inline-tag" && /\S/.test(part.text))) {
-        warning("Content in the summary section will be overwritten by the @inheritDoc tag");
+        warning(i18n.content_in_summary_overwritten_by_inheritdoc_in_comment_at_0(getPosition()));
     }
     if ((inlineInheritDoc.length || inheritDoc.length) && remarks.length) {
-        warning("Content in the @remarks block will be overwritten by the @inheritDoc tag");
+        warning(i18n.content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0(getPosition()));
     }
 }
 const aliasedTags = new Map([["@return", "@returns"]]);
-function blockTag(comment, lexer, config, warning) {
+function blockTag(comment, lexer, config, i18n, warning) {
     const blockTag = lexer.take();
     (0, assert_1.ok)(blockTag.kind === lexer_1.TokenSyntaxKind.Tag, "blockTag called not at the start of a block tag."); // blockContent is broken if this fails.
     const tagName = aliasedTags.get(blockTag.text) || blockTag.text;
     let content;
     if (tagName === "@example") {
-        return exampleBlock(comment, lexer, config, warning);
+        return exampleBlock(comment, lexer, config, i18n, warning);
     }
     else if (["@default", "@defaultValue"].includes(tagName) &&
         config.jsDocCompatibility.defaultTag) {
-        content = defaultBlockContent(comment, lexer, config, warning);
+        content = defaultBlockContent(comment, lexer, config, i18n, warning);
     }
     else {
-        content = blockContent(comment, lexer, config, warning);
+        content = blockContent(comment, lexer, config, i18n, warning);
     }
     return new models_1.CommentTag(tagName, content);
 }
@@ -142,13 +244,13 @@ function blockTag(comment, lexer, config, warning) {
  * The `@default` tag gets a special case because otherwise we will produce many warnings
  * about unescaped/mismatched/missing braces in legacy JSDoc comments
  */
-function defaultBlockContent(comment, lexer, config, warning) {
+function defaultBlockContent(comment, lexer, config, i18n, warning) {
     lexer.mark();
-    const content = blockContent(comment, lexer, config, () => { });
+    const content = blockContent(comment, lexer, config, i18n, () => { });
     const end = lexer.done() || lexer.peek();
     lexer.release();
     if (content.some((part) => part.kind === "code")) {
-        return blockContent(comment, lexer, config, warning);
+        return blockContent(comment, lexer, config, i18n, warning);
     }
     const tokens = [];
     while ((lexer.done() || lexer.peek()) !== end) {
@@ -171,9 +273,9 @@ function defaultBlockContent(comment, lexer, config, warning) {
  *
  * In TSDoc, we also want to treat the first line of the block as the example name.
  */
-function exampleBlock(comment, lexer, config, warning) {
+function exampleBlock(comment, lexer, config, i18n, warning) {
     lexer.mark();
-    const content = blockContent(comment, lexer, config, () => { });
+    const content = blockContent(comment, lexer, config, i18n, () => { });
     const end = lexer.done() || lexer.peek();
     lexer.release();
     if (!config.jsDocCompatibility.exampleTag ||
@@ -205,8 +307,7 @@ function exampleBlock(comment, lexer, config, warning) {
                 case lexer_1.TokenSyntaxKind.CloseBrace:
                 case lexer_1.TokenSyntaxKind.OpenBrace:
                     if (!warnedAboutRichNameContent) {
-                        warning("The first line of an example tag will be taken literally as" +
-                            " the example name, and should only contain text.", lexer.peek());
+                        warning(i18n.example_tag_literal_name(), lexer.peek());
                         warnedAboutRichNameContent = true;
                     }
                     exampleName += lexer.take().text;
@@ -215,7 +316,7 @@ function exampleBlock(comment, lexer, config, warning) {
                     (0, utils_1.assertNever)(next.kind);
             }
         }
-        const content = blockContent(comment, lexer, config, warning);
+        const content = blockContent(comment, lexer, config, i18n, warning);
         const tag = new models_1.CommentTag("@example", content);
         if (exampleName.trim()) {
             tag.name = exampleName.trim();
@@ -250,7 +351,11 @@ function exampleBlock(comment, lexer, config, warning) {
         ]);
     }
 }
-function blockContent(comment, lexer, config, warning) {
+/**
+ * If you change this, also look at parseCommentString as it
+ * likely needs similar modifications to ensure parsing is consistent.
+ */
+function blockContent(comment, lexer, config, i18n, warning) {
     const content = [];
     let atNewLine = true;
     loop: while (!lexer.done()) {
@@ -267,7 +372,7 @@ function blockContent(comment, lexer, config, warning) {
             case lexer_1.TokenSyntaxKind.Tag:
                 if (next.text === "@inheritdoc") {
                     if (!config.jsDocCompatibility.inheritDocTag) {
-                        warning("The @inheritDoc tag should be properly capitalized", next);
+                        warning(i18n.inheritdoc_tag_properly_capitalized(), next);
                     }
                     next.text = "@inheritDoc";
                 }
@@ -278,7 +383,7 @@ function blockContent(comment, lexer, config, warning) {
                 else if (!atNewLine && !config.blockTags.has(next.text)) {
                     // Treat unknown tag as a modifier, but warn about it.
                     comment.modifierTags.add(next.text);
-                    warning(`Treating unrecognized tag "${next.text}" as a modifier tag`, next);
+                    warning(i18n.treating_unrecognized_tag_0_as_modifier(next.text), next);
                     break;
                 }
                 else {
@@ -292,12 +397,12 @@ function blockContent(comment, lexer, config, warning) {
             case lexer_1.TokenSyntaxKind.CloseBrace:
                 // Unmatched closing brace, generate a warning, and treat it as text.
                 if (!config.jsDocCompatibility.ignoreUnescapedBraces) {
-                    warning(`Unmatched closing brace`, next);
+                    warning(i18n.unmatched_closing_brace(), next);
                 }
                 content.push({ kind: "text", text: next.text });
                 break;
             case lexer_1.TokenSyntaxKind.OpenBrace:
-                inlineTag(lexer, content, config, warning);
+                inlineTag(lexer, content, config, i18n, warning);
                 consume = false;
                 break;
             default:
@@ -334,7 +439,7 @@ function blockContent(comment, lexer, config, warning) {
     }
     return content;
 }
-function inlineTag(lexer, block, config, warning) {
+function inlineTag(lexer, block, config, i18n, warning) {
     const openBrace = lexer.take();
     // Now skip whitespace to grab the tag name.
     // If the first non-whitespace text after the brace isn't a tag,
@@ -342,7 +447,7 @@ function inlineTag(lexer, block, config, warning) {
     if (lexer.done() ||
         ![lexer_1.TokenSyntaxKind.Text, lexer_1.TokenSyntaxKind.Tag].includes(lexer.peek().kind)) {
         if (!config.jsDocCompatibility.ignoreUnescapedBraces) {
-            warning("Encountered an unescaped open brace without an inline tag", openBrace);
+            warning(i18n.unescaped_open_brace_without_inline_tag(), openBrace);
         }
         block.push({ kind: "text", text: openBrace.text });
         return;
@@ -353,7 +458,7 @@ function inlineTag(lexer, block, config, warning) {
             (!/^\s+$/.test(tagName.text) ||
                 lexer.peek().kind != lexer_1.TokenSyntaxKind.Tag))) {
         if (!config.jsDocCompatibility.ignoreUnescapedBraces) {
-            warning("Encountered an unescaped open brace without an inline tag", openBrace);
+            warning(i18n.unescaped_open_brace_without_inline_tag(), openBrace);
         }
         block.push({ kind: "text", text: openBrace.text + tagName.text });
         return;
@@ -362,7 +467,7 @@ function inlineTag(lexer, block, config, warning) {
         tagName = lexer.take();
     }
     if (!config.inlineTags.has(tagName.text)) {
-        warning(`Encountered an unknown inline tag "${tagName.text}"`, tagName);
+        warning(i18n.unknown_inline_tag_0(tagName.text), tagName);
     }
     const content = [];
     // At this point, we know we have an inline tag. Treat everything following as plain text,
@@ -370,12 +475,12 @@ function inlineTag(lexer, block, config, warning) {
     while (!lexer.done() && lexer.peek().kind !== lexer_1.TokenSyntaxKind.CloseBrace) {
         const token = lexer.take();
         if (token.kind === lexer_1.TokenSyntaxKind.OpenBrace) {
-            warning("Encountered an open brace within an inline tag, this is likely a mistake", token);
+            warning(i18n.open_brace_within_inline_tag(), token);
         }
         content.push(token.kind === lexer_1.TokenSyntaxKind.NewLine ? " " : token.text);
     }
     if (lexer.done()) {
-        warning("Inline tag is not closed", openBrace);
+        warning(i18n.inline_tag_not_closed(), openBrace);
     }
     else {
         lexer.take(); // Close brace

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

@@ -1,2 +1,8 @@
-import { Token } from "./lexer";
+import { type Token } from "./lexer";
+/**
+ * Note: This lexer intentionally *only* recognizes inline tags and code blocks.
+ * This is because it is intended for use on markdown documents, and we shouldn't
+ * take some stray `@user` mention within a "Thanks" section of someone's changelog
+ * as starting a block!
+ */
 export declare function lexCommentString(file: string): Generator<Token, undefined, undefined>;

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

@@ -1,16 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.lexCommentString = void 0;
+exports.lexCommentString = lexCommentString;
 const lexer_1 = require("./lexer");
+/**
+ * Note: This lexer intentionally *only* recognizes inline tags and code blocks.
+ * This is because it is intended for use on markdown documents, and we shouldn't
+ * take some stray `@user` mention within a "Thanks" section of someone's changelog
+ * as starting a block!
+ */
 function* lexCommentString(file) {
     // Wrapper around our real lex function to collapse adjacent text tokens.
     let textToken;
     for (const token of lexCommentString2(file)) {
-        if (token.kind === lexer_1.TokenSyntaxKind.Text) {
+        if (token.kind === lexer_1.TokenSyntaxKind.Text ||
+            token.kind === lexer_1.TokenSyntaxKind.NewLine) {
             if (textToken) {
                 textToken.text += token.text;
             }
             else {
+                token.kind = lexer_1.TokenSyntaxKind.Text;
                 textToken = token;
             }
         }
@@ -27,7 +35,6 @@ function* lexCommentString(file) {
     }
     return;
 }
-exports.lexCommentString = lexCommentString;
 function* lexCommentString2(file) {
     let pos = 0;
     let end = file.length;
@@ -40,7 +47,7 @@ function* lexCommentString2(file) {
         end--;
     }
     let lineStart = true;
-    let braceStartsType = false;
+    let expectingTag = false;
     for (;;) {
         if (pos >= end) {
             return;
@@ -52,19 +59,15 @@ function* lexCommentString2(file) {
             case "\n":
                 yield makeToken(lexer_1.TokenSyntaxKind.NewLine, 1);
                 lineStart = true;
+                expectingTag = false;
                 break;
             case "{":
-                if (braceStartsType && nextNonWs(pos + 1) !== "@") {
-                    yield makeToken(lexer_1.TokenSyntaxKind.TypeAnnotation, findEndOfType(pos) - pos);
-                    braceStartsType = false;
-                }
-                else {
-                    yield makeToken(lexer_1.TokenSyntaxKind.OpenBrace, 1);
-                }
+                yield makeToken(lexer_1.TokenSyntaxKind.OpenBrace, 1);
+                expectingTag = true;
                 break;
             case "}":
                 yield makeToken(lexer_1.TokenSyntaxKind.CloseBrace, 1);
-                braceStartsType = false;
+                expectingTag = false;
                 break;
             case "`": {
                 // Markdown's code rules are a royal pain. This could be one of several things.
@@ -72,7 +75,6 @@ function* lexCommentString2(file) {
                 // 2. Code block: <3 ticks><language, no ticks>\n<text>\n<3 ticks>\n
                 // 3. Unmatched tick(s), not code, but part of some text.
                 // We don't quite handle #2 correctly yet. PR welcome!
-                braceStartsType = false;
                 let tickCount = 1;
                 let lookahead = pos;
                 while (lookahead + 1 < end && file[lookahead + 1] === "`") {
@@ -91,6 +93,7 @@ function* lexCommentString2(file) {
                             text: codeText.join(""),
                             pos,
                         };
+                        expectingTag = false;
                         pos = lookahead;
                         break;
                     }
@@ -122,10 +125,12 @@ function* lexCommentString2(file) {
                             text: codeText.join(""),
                             pos,
                         };
+                        expectingTag = false;
                         pos = lookahead;
                     }
                     else {
                         yield makeToken(lexer_1.TokenSyntaxKind.Text, tickCount);
+                        expectingTag = false;
                     }
                 }
                 break;
@@ -141,9 +146,9 @@ function* lexCommentString2(file) {
                         lookahead++;
                     }
                 }
-                if (lookahead !== pos + 1 &&
+                if (expectingTag &&
+                    lookahead !== pos + 1 &&
                     (lookahead === end || /[\s}]/.test(file[lookahead]))) {
-                    braceStartsType = true;
                     yield makeToken(lexer_1.TokenSyntaxKind.Tag, lookahead - pos);
                     break;
                 }
@@ -173,7 +178,7 @@ function* lexCommentString2(file) {
                 }
                 textParts.push(file.substring(lookaheadStart, lookahead));
                 if (textParts.some((part) => /\S/.test(part))) {
-                    braceStartsType = false;
+                    expectingTag = false;
                 }
                 // This piece of text had line continuations or escaped text
                 yield {
@@ -201,58 +206,4 @@ function* lexCommentString2(file) {
         }
         return file.startsWith("`".repeat(n), pos) && file[pos + n] !== "`";
     }
-    function findEndOfType(pos) {
-        let openBraces = 0;
-        while (pos < end) {
-            if (file[pos] === "{") {
-                openBraces++;
-            }
-            else if (file[pos] === "}") {
-                if (--openBraces === 0) {
-                    break;
-                }
-            }
-            else if ("`'\"".includes(file[pos])) {
-                pos = findEndOfString(pos);
-            }
-            pos++;
-        }
-        if (pos < end && file[pos] === "}") {
-            pos++;
-        }
-        return pos;
-    }
-    function findEndOfString(pos) {
-        const endOfString = file[pos];
-        pos++;
-        while (pos < end) {
-            if (file[pos] === endOfString) {
-                break;
-            }
-            else if (file[pos] === "\\") {
-                pos++; // Skip escaped character
-            }
-            else if (endOfString === "`" &&
-                file[pos] === "$" &&
-                file[pos + 1] === "{") {
-                // Template literal with data inside a ${}
-                while (pos < end && file[pos] !== "}") {
-                    if ("`'\"".includes(file[pos])) {
-                        pos = findEndOfString(pos) + 1;
-                    }
-                    else {
-                        pos++;
-                    }
-                }
-            }
-            pos++;
-        }
-        return pos;
-    }
-    function nextNonWs(pos) {
-        while (pos < end && /\s/.test(file[pos])) {
-            pos++;
-        }
-        return file[pos];
-    }
 }

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractTagName = void 0;
+exports.extractTagName = extractTagName;
 /**
  * Determines the name of the parameter/template/property from the tag content
  * when processing `@param x`
@@ -50,7 +50,6 @@ function extractTagName(text) {
         newText: text.substring(pos),
     };
 }
-exports.extractTagName = extractTagName;
 function skipWs(text, pos) {
     return skipWith(text, pos, /\s/);
 }

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

@@ -1,6 +1,7 @@
 import ts from "typescript";
-import { Reflection, ProjectReflection, DeclarationReflection, ReflectionKind } from "../models/index";
+import { type Reflection, type ProjectReflection, DeclarationReflection, ReflectionKind, type DocumentReflection } from "../models/index";
 import type { Converter } from "./converter";
+import type { TranslationProxy } from "../internationalization/internationalization";
 /**
  * The context describes the current state the converter is in.
  */
@@ -13,6 +14,10 @@ export declare class Context {
      * The TypeChecker instance returned by the TypeScript compiler.
      */
     get checker(): ts.TypeChecker;
+    /**
+     * Translation interface for log messages.
+     */
+    get i18n(): TranslationProxy;
     /**
      * The program currently being converted.
      * Accessing this property will throw if a source file is not currently being converted.
@@ -56,7 +61,7 @@ export declare class Context {
     createDeclarationReflection(kind: ReflectionKind, symbol: ts.Symbol | undefined, exportSymbol: ts.Symbol | undefined, nameOverride?: string): DeclarationReflection;
     postReflectionCreation(reflection: Reflection, symbol: ts.Symbol | undefined, exportSymbol: ts.Symbol | undefined): void;
     finalizeDeclarationReflection(reflection: DeclarationReflection): void;
-    addChild(reflection: DeclarationReflection): void;
+    addChild(reflection: DeclarationReflection | DocumentReflection): void;
     shouldIgnore(symbol: ts.Symbol): boolean;
     /**
      * Register a newly generated reflection. All created reflections should be

package/dist/lib/converter/context.js

@@ -22,6 +22,12 @@ class Context {
     get checker() {
         return this.program.getTypeChecker();
     }
+    /**
+     * Translation interface for log messages.
+     */
+    get i18n() {
+        return this.converter.application.i18n;
+    }
     /**
      * The program currently being converted.
      * Accessing this property will throw if a source file is not currently being converted.
@@ -139,8 +145,7 @@ class Context {
     }
     addChild(reflection) {
         if (this.scope instanceof index_1.ContainerReflection) {
-            this.scope.children ??= [];
-            this.scope.children.push(reflection);
+            this.scope.addChild(reflection);
         }
     }
     shouldIgnore(symbol) {

package/dist/lib/converter/convert-expression.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertExpression = exports.convertDefaultValue = void 0;
+exports.convertDefaultValue = convertDefaultValue;
+exports.convertExpression = convertExpression;
 const typescript_1 = __importDefault(require("typescript"));
 /**
  * Return the default value of the given node.
@@ -20,7 +21,6 @@ function convertDefaultValue(node) {
         return undefined;
     }
 }
-exports.convertDefaultValue = convertDefaultValue;
 function convertExpression(expression) {
     switch (expression.kind) {
         case typescript_1.default.SyntaxKind.StringLiteral:
@@ -57,4 +57,3 @@ function convertExpression(expression) {
     // Show that there was a value, but not specifics.
     return "...";
 }
-exports.convertExpression = convertExpression;

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

@@ -1,6 +1,6 @@
 import ts from "typescript";
 import type { Application } from "../application";
-import { Comment, CommentDisplayPart, ProjectReflection, Reflection, ReflectionSymbolId, SomeType } from "../models/index";
+import { Comment, type CommentDisplayPart, ProjectReflection, type Reflection, type ReflectionSymbolId, type SomeType } from "../models/index";
 import { Context } from "./context";
 import { ConverterComponent } from "./components";
 import { ChildableComponent } from "../utils/component";
@@ -8,7 +8,7 @@ import { MinimalSourceFile } from "../utils";
 import type { DocumentationEntryPoint } from "../utils/entry-point";
 import type { CommentParserConfig } from "./comments";
 import type { CommentStyle, ValidationOptions } from "../utils/options/declaration";
-import { ExternalSymbolResolver, ExternalResolveResult } from "./comments/linkResolver";
+import { type ExternalSymbolResolver, type ExternalResolveResult } from "./comments/linkResolver";
 import type { DeclarationReference } from "./comments/declarationReference";
 /**
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
@@ -114,6 +114,8 @@ export declare class Converter extends ChildableComponent<Application, Converter
      */
     convert(entryPoints: readonly DocumentationEntryPoint[]): ProjectReflection;
     /** @internal */
+    addProjectDocuments(project: ProjectReflection): void;
+    /** @internal */
     convertSymbol(context: Context, symbol: ts.Symbol, exportSymbol?: ts.Symbol): void;
     /**
      * Convert the given TypeScript type into its TypeDoc type reflection.
@@ -126,7 +128,10 @@ 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): Comment;
+    parseRawComment(file: MinimalSourceFile): {
+        content: CommentDisplayPart[];
+        frontmatter: Record<string, unknown>;
+    };
     /**
      * Adds a new resolver that the theme can use to try to figure out how to link to a symbol declared
      * by a third-party library which is not included in the documentation.