typedoc 0.26.0 → 0.26.2

package/dist/lib/application.js

@@ -496,6 +496,7 @@ let Application = (() => {
                 this.logger.error(this.i18n.failed_to_find_packages());
                 return;
             }
+            const origFiles = this.files;
             const origOptions = this.options;
             const projects = [];
             const projectsToConvert = [];
@@ -526,14 +527,23 @@ let Application = (() => {
             for (const { dir, options } of projectsToConvert) {
                 this.logger.info(this.i18n.converting_project_at_0((0, paths_1.nicePath)(dir)));
                 this.options = options;
-                const project = await this.convert();
+                this.files = new FileRegistry_1.ValidatingFileRegistry();
+                let project = await this.convert();
                 if (project) {
                     this.validate(project);
-                    projects.push(this.serializer.projectToObject(project, process.cwd()));
+                    const serialized = this.serializer.projectToObject(project, process.cwd());
+                    projects.push(serialized);
                 }
+                // When debugging memory issues, it's useful to set these
+                // here so that a breakpoint on resetReflectionID below
+                // gets the memory as it ought to be with all TS objects released.
+                project = undefined;
+                this.files = undefined;
+                // global.gc!();
                 (0, abstract_1.resetReflectionID)();
             }
             this.options = origOptions;
+            this.files = origFiles;
             if (projects.length !== packageDirs.length) {
                 this.logger.error(this.i18n.failed_to_convert_packages());
                 return;

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

@@ -6,12 +6,9 @@ export interface DiscoveredComment {
     file: ts.SourceFile;
     ranges: ts.CommentRange[];
     jsDoc: ts.JSDoc | undefined;
+    inheritedFromParentDeclaration: boolean;
 }
-export declare function discoverFileComments(node: ts.SourceFile, commentStyle: CommentStyle): {
-    file: ts.SourceFile;
-    ranges: ts.CommentRange[];
-    jsDoc: ts.JSDoc | undefined;
-}[];
+export declare function discoverFileComments(node: ts.SourceFile, commentStyle: CommentStyle): DiscoveredComment[];
 export declare function discoverNodeComment(node: ts.Node, commentStyle: CommentStyle): DiscoveredComment | undefined;
-export declare function discoverComment(symbol: ts.Symbol, kind: ReflectionKind, logger: Logger, commentStyle: CommentStyle): DiscoveredComment | undefined;
-export declare function discoverSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, commentStyle: CommentStyle): DiscoveredComment | undefined;
+export declare function discoverComment(symbol: ts.Symbol, kind: ReflectionKind, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker): DiscoveredComment | undefined;
+export declare function discoverSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, checker: ts.TypeChecker, commentStyle: CommentStyle): DiscoveredComment | undefined;

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

@@ -13,6 +13,7 @@ const utils_1 = require("../../utils");
 const declaration_1 = require("../../utils/options/declaration");
 const paths_1 = require("../../utils/paths");
 const assert_1 = require("assert");
+const array_1 = require("../../utils/array");
 const variablePropertyKinds = [
     typescript_1.default.SyntaxKind.PropertyDeclaration,
     typescript_1.default.SyntaxKind.PropertySignature,
@@ -128,6 +129,7 @@ function discoverFileComments(node, commentStyle) {
             file: node,
             ranges,
             jsDoc: findJsDocForComment(node, ranges),
+            inheritedFromParentDeclaration: false,
         };
     });
 }
@@ -141,99 +143,119 @@ function discoverNodeComment(node, commentStyle) {
             file: node.getSourceFile(),
             ranges: selectedDocComment,
             jsDoc: findJsDocForComment(node, selectedDocComment),
+            inheritedFromParentDeclaration: false,
         };
     }
 }
-function discoverComment(symbol, kind, logger, commentStyle) {
+function checkCommentDeclarations(commentNodes, reverse, commentStyle) {
+    const discovered = [];
+    for (const { node, inheritedFromParentDeclaration } of commentNodes) {
+        const text = node.getSourceFile().text;
+        const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
+        if (reverse) {
+            comments.reverse();
+        }
+        const selectedDocComment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
+        if (selectedDocComment) {
+            discovered.push({
+                file: node.getSourceFile(),
+                ranges: selectedDocComment,
+                jsDoc: findJsDocForComment(node, selectedDocComment),
+                inheritedFromParentDeclaration,
+            });
+        }
+    }
+    return discovered;
+}
+function discoverComment(symbol, kind, logger, commentStyle, checker) {
     // For a module comment, we want the first one defined in the file,
     // not the last one, since that will apply to the import or declaration.
     const reverse = !symbol.declarations?.some(typescript_1.default.isSourceFile);
-    const discovered = [];
-    const seen = new Set();
-    for (const decl of symbol.declarations || []) {
-        const text = decl.getSourceFile().text;
-        if (wantedKinds[kind].includes(decl.kind)) {
-            const node = declarationToCommentNode(decl);
-            if (!node || seen.has(node)) {
-                continue;
-            }
-            seen.add(node);
-            // Special behavior here!
-            // Signatures and symbols have two distinct discovery methods as of TypeDoc 0.26.
-            // This method discovers comments for symbols, and function-likes will only have
-            // a symbol comment if there is more than one signature (== more than one declaration)
-            // and there is a comment on the implementation signature.
-            if (kind & models_1.ReflectionKind.ContainsCallSignatures &&
-                [
-                    typescript_1.default.SyntaxKind.FunctionDeclaration,
-                    typescript_1.default.SyntaxKind.MethodDeclaration,
-                    typescript_1.default.SyntaxKind.Constructor,
-                ].includes(node.kind) &&
-                (symbol.declarations.filter((d) => wantedKinds[kind].includes(d.kind)).length === 1 ||
-                    !node.body)) {
-                continue;
-            }
-            const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
-            if (reverse) {
-                comments.reverse();
-            }
-            const selectedDocComment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
-            if (selectedDocComment) {
-                discovered.push({
-                    file: decl.getSourceFile(),
-                    ranges: selectedDocComment,
-                    jsDoc: findJsDocForComment(node, selectedDocComment),
+    const wantedDeclarations = (0, array_1.filter)(symbol.declarations, (decl) => wantedKinds[kind].includes(decl.kind));
+    const commentNodes = wantedDeclarations.flatMap((decl) => declarationToCommentNodes(decl, checker));
+    // Special behavior here!
+    // Signatures and symbols have two distinct discovery methods as of TypeDoc 0.26.
+    // This method discovers comments for symbols, and function-likes will only have
+    // a symbol comment if there is more than one signature (== more than one declaration)
+    // and there is a comment on the implementation signature.
+    if (kind & models_1.ReflectionKind.ContainsCallSignatures) {
+        const canHaveOverloads = wantedDeclarations.some((node) => [
+            typescript_1.default.SyntaxKind.FunctionDeclaration,
+            typescript_1.default.SyntaxKind.MethodDeclaration,
+            typescript_1.default.SyntaxKind.Constructor,
+        ].includes(node.kind));
+        const isOverloaded = canHaveOverloads && wantedDeclarations.length > 1;
+        if (isOverloaded) {
+            commentNodes.length = 0;
+            const implementationNode = wantedDeclarations.find((node) => node.body);
+            if (implementationNode) {
+                commentNodes.push({
+                    node: implementationNode,
+                    inheritedFromParentDeclaration: false,
                 });
             }
         }
+        else if (canHaveOverloads) {
+            // Single signature function, function reflection doesn't get a comment,
+            // the signatures do.
+            commentNodes.length = 0;
+        }
+        else {
+            // Variable declaration which happens to include signatures.
+        }
     }
+    const discovered = checkCommentDeclarations(commentNodes, reverse, commentStyle);
     switch (discovered.length) {
         case 0:
             return undefined;
         case 1:
             return discovered[0];
         default: {
-            logger.warn(logger.i18n.symbol_0_has_multiple_declarations_with_comment(symbol.name));
-            const locations = discovered.map(({ file, ranges: [{ pos }] }) => {
-                const path = (0, paths_1.nicePath)(file.fileName);
-                const line = typescript_1.default.getLineAndCharacterOfPosition(file, pos).line + 1;
-                return `${path}:${line}`;
-            });
-            logger.info(logger.i18n.comments_for_0_are_declared_at_1(symbol.name, locations.join("\n\t")));
+            if (discovered.filter((n) => !n.inheritedFromParentDeclaration)
+                .length > 1) {
+                logger.warn(logger.i18n.symbol_0_has_multiple_declarations_with_comment(symbol.name));
+                const locations = discovered.map(({ file, ranges: [{ pos }] }) => {
+                    const path = (0, paths_1.nicePath)(file.fileName);
+                    const line = typescript_1.default.getLineAndCharacterOfPosition(file, pos).line +
+                        1;
+                    return `${path}:${line}`;
+                });
+                logger.info(logger.i18n.comments_for_0_are_declared_at_1(symbol.name, locations.join("\n\t")));
+            }
             return discovered[0];
         }
     }
 }
-function discoverSignatureComment(declaration, commentStyle) {
-    const node = declarationToCommentNode(declaration);
-    if (!node) {
-        return;
-    }
-    if (typescript_1.default.isJSDocSignature(node)) {
-        const comment = node.parent.parent;
-        (0, assert_1.ok)(typescript_1.default.isJSDoc(comment));
-        return {
-            file: node.getSourceFile(),
-            ranges: [
-                {
-                    kind: typescript_1.default.SyntaxKind.MultiLineCommentTrivia,
-                    pos: comment.pos,
-                    end: comment.end,
-                },
-            ],
-            jsDoc: comment,
-        };
-    }
-    const text = node.getSourceFile().text;
-    const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
-    comments.reverse();
-    const comment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
-    if (comment) {
-        return {
-            file: node.getSourceFile(),
-            ranges: comment,
-            jsDoc: findJsDocForComment(node, comment),
-        };
+function discoverSignatureComment(declaration, checker, commentStyle) {
+    for (const { node, inheritedFromParentDeclaration, } of declarationToCommentNodes(declaration, checker)) {
+        if (typescript_1.default.isJSDocSignature(node)) {
+            const comment = node.parent.parent;
+            (0, assert_1.ok)(typescript_1.default.isJSDoc(comment));
+            return {
+                file: node.getSourceFile(),
+                ranges: [
+                    {
+                        kind: typescript_1.default.SyntaxKind.MultiLineCommentTrivia,
+                        pos: comment.pos,
+                        end: comment.end,
+                    },
+                ],
+                jsDoc: comment,
+                inheritedFromParentDeclaration,
+            };
+        }
+        const text = node.getSourceFile().text;
+        const comments = collectCommentRanges(typescript_1.default.getLeadingCommentRanges(text, node.pos));
+        comments.reverse();
+        const comment = comments.find((ranges) => permittedRange(text, ranges, commentStyle));
+        if (comment) {
+            return {
+                file: node.getSourceFile(),
+                ranges: comment,
+                jsDoc: findJsDocForComment(node, comment),
+                inheritedFromParentDeclaration,
+            };
+        }
     }
 }
 function findJsDocForComment(node, ranges) {
@@ -282,7 +304,7 @@ function getRootModuleDeclaration(node) {
     }
     return node;
 }
-function declarationToCommentNode(node) {
+function declarationToCommentNodeIgnoringParents(node) {
     // ts.SourceFile is a counterexample
     if (!node.parent)
         return node;
@@ -324,7 +346,54 @@ function declarationToCommentNode(node) {
     if (typescript_1.default.SyntaxKind.NamespaceExport === node.kind) {
         return node.parent;
     }
-    return node;
+}
+function declarationToCommentNodes(node, checker) {
+    const commentNode = declarationToCommentNodeIgnoringParents(node);
+    if (commentNode) {
+        return [
+            {
+                node: commentNode,
+                inheritedFromParentDeclaration: false,
+            },
+        ];
+    }
+    const result = [
+        {
+            node,
+            inheritedFromParentDeclaration: false,
+        },
+    ];
+    const seenSymbols = new Set();
+    const bases = findBaseOfDeclaration(checker, node, (symbol) => {
+        if (!seenSymbols.has(symbol)) {
+            seenSymbols.add(symbol);
+            return symbol.declarations?.map((node) => declarationToCommentNodeIgnoringParents(node) || node);
+        }
+    });
+    for (const parentCommentNode of bases || []) {
+        result.push({
+            node: parentCommentNode,
+            inheritedFromParentDeclaration: true,
+        });
+    }
+    return result;
+}
+// Lifted from the TS source, with a couple minor modifications
+function findBaseOfDeclaration(checker, declaration, cb) {
+    const classOrInterfaceDeclaration = declaration.parent?.kind === typescript_1.default.SyntaxKind.Constructor
+        ? declaration.parent.parent
+        : declaration.parent;
+    if (!classOrInterfaceDeclaration)
+        return;
+    const isStaticMember = typescript_1.default.getCombinedModifierFlags(declaration) & typescript_1.default.ModifierFlags.Static;
+    return (0, array_1.firstDefined)(typescript_1.default.getAllSuperTypeNodes(classOrInterfaceDeclaration), (superTypeNode) => {
+        const baseType = checker.getTypeAtLocation(superTypeNode);
+        const type = isStaticMember && baseType.symbol
+            ? checker.getTypeOfSymbol(baseType.symbol)
+            : baseType;
+        const symbol = checker.getPropertyOfType(type, declaration.symbol.name);
+        return symbol ? cb(symbol) : undefined;
+    });
 }
 /**
  * Separate comment ranges into arrays so that multiple line comments are kept together

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

@@ -8,10 +8,13 @@ export interface CommentParserConfig {
     inlineTags: Set<string>;
     modifierTags: Set<string>;
     jsDocCompatibility: JsDocCompatibility;
+    suppressCommentWarningsInDeclarationFiles: boolean;
+    useTsLinkResolution: boolean;
+    commentStyle: CommentStyle;
 }
 export declare function clearCommentCache(): void;
-export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
-export declare function getNodeComment(node: ts.Node, moduleComment: boolean, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
-export declare function getFileComment(file: ts.SourceFile, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
-export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker, files: FileRegistry): Comment | undefined;
+export declare function getNodeComment(node: ts.Node, moduleComment: boolean, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getFileComment(file: ts.SourceFile, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker, files: FileRegistry): Comment | undefined;
 export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;

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

@@ -38,7 +38,10 @@ function getCommentWithCache(discovered, config, logger, checker, files) {
     const { file, ranges, jsDoc } = discovered;
     const cache = commentCache.get(file) || new Map();
     if (cache.has(ranges[0].pos)) {
-        return cache.get(ranges[0].pos).clone();
+        const clone = cache.get(ranges[0].pos).clone();
+        clone.inheritedFromParentDeclaration =
+            discovered.inheritedFromParentDeclaration;
+        return clone;
     }
     let comment;
     switch (ranges[0].kind) {
@@ -52,12 +55,14 @@ function getCommentWithCache(discovered, config, logger, checker, files) {
             (0, utils_1.assertNever)(ranges[0].kind);
     }
     comment.discoveryId = ++commentDiscoveryId;
+    comment.inheritedFromParentDeclaration =
+        discovered.inheritedFromParentDeclaration;
     cache.set(ranges[0].pos, comment);
     commentCache.set(file, cache);
     return comment.clone();
 }
 function getCommentImpl(commentSource, config, logger, moduleComment, checker, files) {
-    const comment = getCommentWithCache(commentSource, config, logger, checker, files);
+    const comment = getCommentWithCache(commentSource, config, logger, config.useTsLinkResolution ? checker : undefined, files);
     if (comment?.getTag("@import") || comment?.getTag("@license")) {
         return;
     }
@@ -78,7 +83,7 @@ function getCommentImpl(commentSource, config, logger, moduleComment, checker, f
     }
     return comment;
 }
-function getComment(symbol, kind, config, logger, commentStyle, checker, files) {
+function getComment(symbol, kind, config, logger, checker, files) {
     const declarations = symbol.declarations || [];
     if (declarations.length &&
         declarations.every((d) => jsDocCommentKinds.includes(d.kind))) {
@@ -86,7 +91,7 @@ function getComment(symbol, kind, config, logger, commentStyle, checker, files)
     }
     const sf = declarations.find(typescript_1.default.isSourceFile);
     if (sf) {
-        return getFileComment(sf, config, logger, commentStyle, checker, files);
+        return getFileComment(sf, config, logger, checker, files);
     }
     const isModule = declarations.some((decl) => {
         if (typescript_1.default.isModuleDeclaration(decl) && typescript_1.default.isStringLiteral(decl.name)) {
@@ -94,18 +99,18 @@ function getComment(symbol, kind, config, logger, commentStyle, checker, files)
         }
         return false;
     });
-    const comment = getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, commentStyle), config, logger, isModule, checker, files);
+    const comment = getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, config.commentStyle, checker), config, logger, isModule, checker, files);
     if (!comment && kind === models_1.ReflectionKind.Property) {
-        return getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker, files);
+        return getConstructorParamPropertyComment(symbol, config, logger, checker, files);
     }
     return comment;
 }
-function getNodeComment(node, moduleComment, config, logger, commentStyle, checker, files) {
-    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, moduleComment, checker, files);
+function getNodeComment(node, moduleComment, config, logger, checker, files) {
+    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, config.commentStyle), config, logger, moduleComment, checker, files);
 }
-function getFileComment(file, config, logger, commentStyle, checker, files) {
-    for (const commentSource of (0, discovery_1.discoverFileComments)(file, commentStyle)) {
-        const comment = getCommentWithCache(commentSource, config, logger, checker, files);
+function getFileComment(file, config, logger, checker, files) {
+    for (const commentSource of (0, discovery_1.discoverFileComments)(file, config.commentStyle)) {
+        const comment = getCommentWithCache(commentSource, config, logger, config.useTsLinkResolution ? checker : undefined, files);
         if (comment?.getTag("@license") || comment?.getTag("@import")) {
             continue;
         }
@@ -116,12 +121,12 @@ function getFileComment(file, config, logger, commentStyle, checker, files) {
         return;
     }
 }
-function getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker, files) {
+function getConstructorParamPropertyComment(symbol, config, logger, checker, files) {
     const decl = symbol.declarations?.find(typescript_1.default.isParameter);
     if (!decl)
         return;
     const ctor = decl.parent;
-    const comment = getSignatureComment(ctor, config, logger, commentStyle, checker, files);
+    const comment = getSignatureComment(ctor, config, logger, checker, files);
     const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
     if (paramTag) {
         const result = new models_1.Comment(paramTag.content);
@@ -129,8 +134,8 @@ function getConstructorParamPropertyComment(symbol, config, logger, commentStyle
         return result;
     }
 }
-function getSignatureComment(declaration, config, logger, commentStyle, checker, files) {
-    return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, commentStyle), config, logger, false, checker, files);
+function getSignatureComment(declaration, config, logger, checker, files) {
+    return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, checker, config.commentStyle), config, logger, false, checker, files);
 }
 function getJsDocComment(declaration, config, logger, checker, files) {
     const file = declaration.getSourceFile();
@@ -150,7 +155,8 @@ function getJsDocComment(declaration, config, logger, checker, files) {
             },
         ],
         jsDoc: parent,
-    }, config, logger, checker, files);
+        inheritedFromParentDeclaration: false,
+    }, config, logger, config.useTsLinkResolution ? checker : undefined, files);
     // And pull out the tag we actually care about.
     if (typescript_1.default.isJSDocEnumTag(declaration)) {
         const result = new models_1.Comment(comment.getTag("@enum")?.content);

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

@@ -79,6 +79,10 @@ function parseComment(tokens, config, file, logger, files) {
     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) {
+        if (config.suppressCommentWarningsInDeclarationFiles &&
+            file.fileName.endsWith(".d.ts")) {
+            return;
+        }
         logger.warn(message, token.pos, file);
     }
 }
@@ -98,13 +102,16 @@ function parseCommentString(tokens, config, file, logger, files) {
             ignoreUnescapedBraces: true,
             inheritDocTag: true,
         },
+        suppressCommentWarningsInDeclarationFiles: true,
     };
+    const reentry = new textParser_1.TextParserReentryState();
     const content = [];
     const lexer = makeLookaheadGenerator(tokens);
     let atNewLine = false;
     while (!lexer.done()) {
         let consume = true;
         const next = lexer.peek();
+        reentry.checkState(next);
         switch (next.kind) {
             case lexer_1.TokenSyntaxKind.TypeAnnotation:
                 // Shouldn't have been produced by our lexer
@@ -114,7 +121,7 @@ function parseCommentString(tokens, config, file, logger, files) {
             case lexer_1.TokenSyntaxKind.Text:
             case lexer_1.TokenSyntaxKind.Tag:
             case lexer_1.TokenSyntaxKind.CloseBrace:
-                (0, textParser_1.textContent)(file.fileName, next, logger.i18n, (msg, token) => logger.warn(msg, token.pos, file), content, files, atNewLine);
+                (0, textParser_1.textContent)(file.fileName, next, logger.i18n, (msg, token) => logger.warn(msg, token.pos, file), content, files, atNewLine, reentry);
                 break;
             case lexer_1.TokenSyntaxKind.Code:
                 content.push({ kind: "code", text: next.text });
@@ -367,8 +374,10 @@ function exampleBlock(comment, lexer, config, i18n, warning, files) {
 function blockContent(comment, lexer, config, i18n, warning, files) {
     const content = [];
     let atNewLine = true;
+    const reentry = new textParser_1.TextParserReentryState();
     loop: while (!lexer.done()) {
         const next = lexer.peek();
+        reentry.checkState(next);
         let consume = true;
         switch (next.kind) {
             case lexer_1.TokenSyntaxKind.NewLine:
@@ -376,7 +385,7 @@ function blockContent(comment, lexer, config, i18n, warning, files) {
                 break;
             case lexer_1.TokenSyntaxKind.Text:
                 (0, textParser_1.textContent)(comment.sourcePath, next, i18n, warning, 
-                /*out*/ content, files, atNewLine);
+                /*out*/ content, files, atNewLine, reentry);
                 break;
             case lexer_1.TokenSyntaxKind.Code:
                 content.push({ kind: "code", text: next.text });

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

@@ -9,8 +9,19 @@ import type { TranslationProxy, TranslatedString } from "../../internationalizat
 import type { CommentDisplayPart } from "../../models";
 import type { FileRegistry } from "../../models/FileRegistry";
 import { type Token } from "./lexer";
+/**
+ * This is incredibly unfortunate. The comment lexer owns the responsibility
+ * for splitting up text into text/code, this is totally fine for HTML links
+ * but for markdown links, ``[`code`](./link)`` is valid, so we need to keep
+ * track of state across calls to {@link textContent}.
+ */
+export declare class TextParserReentryState {
+    withinLinkLabel: boolean;
+    private lastPartWasNewline;
+    checkState(token: Token): void;
+}
 /**
  * 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.
  */
-export declare function textContent(sourcePath: string, token: Token, i18n: TranslationProxy, warning: (msg: TranslatedString, token: Token) => void, outContent: CommentDisplayPart[], files: FileRegistry, atNewLine: boolean): void;
+export declare function textContent(sourcePath: string, token: Token, i18n: TranslationProxy, warning: (msg: TranslatedString, token: Token) => void, outContent: CommentDisplayPart[], files: FileRegistry, atNewLine: boolean, reentry: TextParserReentryState): void;