typedoc 0.28.7 → 0.28.8

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export type { Icons, NavigationElement, PageDefinition, PageHeading, RendererEve
 export { Outputs } from "./lib/output/output.js";
 export { ArgumentsReader, CommentStyle, EntryPointStrategy, normalizePath, Option, OptionDefaults, Options, PackageJsonReader, ParameterHint, ParameterType, TSConfigReader, TypeDocReader, ValidatingFileRegistry, } from "./lib/utils/index.js";
 export type { ArrayDeclarationOption, BooleanDeclarationOption, DeclarationOption, DeclarationOptionBase, DeclarationOptionToOptionType, DocumentationEntryPoint, FancyConsoleLogger, FlagsDeclarationOption, JsDocCompatibility, KeyToDeclaration, ManuallyValidatedOption, MapDeclarationOption, MixedDeclarationOption, NumberDeclarationOption, ObjectDeclarationOption, OptionsReader, OutputSpecification, ParameterTypeToOptionTypeMap, SortStrategy, StringDeclarationOption, TypeDocOptionMap, TypeDocOptions, TypeDocOptionValues, ValidationOptions, } from "./lib/utils/index.js";
-export { type ComponentPath, ConsoleLogger, type DeclarationReference, type EnumKeys, EventDispatcher, EventHooks, type GlobString, i18n, JSX, Logger, LogLevel, type Meaning, type MeaningKeyword, type MinimalNode, MinimalSourceFile, type NormalizedPath, type NormalizedPathOrModule, type SymbolReference, type TranslatedString, translateTagName, } from "#utils";
+export { type ComponentPath, ConsoleLogger, type DeclarationReference, type EnumKeys, EventDispatcher, EventHooks, type GlobString, i18n, JSX, Logger, LogLevel, type Meaning, type MeaningKeyword, type MinimalNode, MinimalSourceFile, type NormalizedPath, type NormalizedPathOrModule, type NormalizedPathOrModuleOrFunction, type SymbolReference, type TranslatedString, translateTagName, } from "#utils";
 export { type Deserializable, Deserializer, type DeserializerComponent, JSONOutput, SerializeEvent, Serializer, type SerializerComponent, type SerializerEvents, } from "./lib/serialization/index.js";
 export * as Internationalization from "./lib/internationalization/index.js";
 export type { TranslatableStrings } from "./lib/internationalization/internationalization.js";

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

@@ -1,3 +1,4 @@
 import ts from "typescript";
 import { type Token } from "./lexer.js";
-export declare function lexBlockComment(file: string, pos?: number, end?: number, jsDoc?: ts.JSDoc | undefined, checker?: ts.TypeChecker | undefined): Generator<Token, undefined, undefined>;
+import type { Context } from "../context.js";
+export declare function lexBlockComment(file: string, pos?: number, end?: number, createSymbolId?: Context["createSymbolId"], jsDoc?: ts.JSDoc | undefined, checker?: ts.TypeChecker | undefined): Generator<Token, undefined, undefined>;

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

@@ -1,11 +1,12 @@
 import ts from "typescript";
 import { TokenSyntaxKind } from "./lexer.js";
 import { resolveAliasedSymbol } from "../utils/symbols.js";
-import { createSymbolId } from "../factories/symbol-id.js";
-export function* lexBlockComment(file, pos = 0, end = file.length, jsDoc = undefined, checker = undefined) {
+export function* lexBlockComment(file, pos = 0, end = file.length, createSymbolId = () => {
+    throw new Error("unreachable");
+}, jsDoc = undefined, checker = undefined) {
     // Wrapper around our real lex function to collapse adjacent text tokens.
     let textToken;
-    for (const token of lexBlockComment2(file, pos, end, getLinkTags(jsDoc), checker)) {
+    for (const token of lexBlockComment2(file, pos, end, getLinkTags(jsDoc), checker, createSymbolId)) {
         if (token.kind === TokenSyntaxKind.Text) {
             if (textToken) {
                 textToken.text += token.text;
@@ -53,7 +54,7 @@ function getLinkTags(jsDoc) {
     }
     return result;
 }
-function* lexBlockComment2(file, pos, end, linkTags, checker) {
+function* lexBlockComment2(file, pos, end, linkTags, checker, createSymbolId) {
     pos += 2; // Leading '/*'
     end -= 2; // Trailing '*/'
     if (pos < end && file[pos] === "*") {
@@ -208,7 +209,7 @@ function* lexBlockComment2(file, pos, end, linkTags, checker) {
                 }
                 if (lookahead !== pos + 1) {
                     while (lookahead < end &&
-                        /[a-z0-9]/i.test(file[lookahead])) {
+                        /[a-z0-9-]/i.test(file[lookahead])) {
                         lookahead++;
                     }
                 }

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

@@ -3,6 +3,7 @@ import { Comment, ReflectionKind } from "../../models/index.js";
 import type { CommentStyle, JsDocCompatibility } from "../../utils/options/declaration.js";
 import type { FileRegistry } from "../../models/FileRegistry.js";
 import { type Logger } from "#utils";
+import type { Context } from "../context.js";
 export interface CommentParserConfig {
     blockTags: Set<string>;
     inlineTags: Set<string>;
@@ -12,9 +13,23 @@ export interface CommentParserConfig {
     useTsLinkResolution: boolean;
     commentStyle: CommentStyle;
 }
+export interface CommentContext {
+    config: CommentParserConfig;
+    logger: Logger;
+    checker: ts.TypeChecker;
+    files: FileRegistry;
+    createSymbolId: Context["createSymbolId"];
+}
+export interface CommentContextOptionalChecker {
+    config: CommentParserConfig;
+    logger: Logger;
+    checker?: ts.TypeChecker | undefined;
+    files: FileRegistry;
+    createSymbolId: Context["createSymbolId"];
+}
 export declare function clearCommentCache(): void;
-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;
+export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, context: CommentContext): Comment | undefined;
+export declare function getNodeComment(node: ts.Node, moduleComment: boolean, context: CommentContext): Comment | undefined;
+export declare function getFileComment(file: ts.SourceFile, context: CommentContext): Comment | undefined;
+export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, context: CommentContext): Comment | undefined;
+export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, context: CommentContext): Comment | undefined;

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

@@ -21,7 +21,7 @@ export function clearCommentCache() {
     commentCache = new WeakMap();
     commentDiscoveryId = 0;
 }
-function getCommentWithCache(discovered, config, logger, checker, files) {
+function getCommentWithCache(discovered, context) {
     if (!discovered)
         return;
     const { file, ranges, jsDoc } = discovered;
@@ -34,10 +34,10 @@ function getCommentWithCache(discovered, config, logger, checker, files) {
     let comment;
     switch (ranges[0].kind) {
         case ts.SyntaxKind.MultiLineCommentTrivia:
-            comment = parseComment(lexBlockComment(file.text, ranges[0].pos, ranges[0].end, jsDoc, checker), config, file, logger, files);
+            comment = parseComment(lexBlockComment(file.text, ranges[0].pos, ranges[0].end, context.createSymbolId, jsDoc, context.checker), file, context);
             break;
         case ts.SyntaxKind.SingleLineCommentTrivia:
-            comment = parseComment(lexLineComments(file.text, ranges), config, file, logger, files);
+            comment = parseComment(lexLineComments(file.text, ranges), file, context);
             break;
         default:
             assertNever(ranges[0].kind);
@@ -48,8 +48,11 @@ function getCommentWithCache(discovered, config, logger, checker, files) {
     commentCache.set(file, cache);
     return comment.clone();
 }
-function getCommentImpl(commentSource, config, logger, moduleComment, checker, files) {
-    const comment = getCommentWithCache(commentSource, config, logger, config.useTsLinkResolution ? checker : undefined, files);
+function getCommentImpl(commentSource, moduleComment, context) {
+    const comment = getCommentWithCache(commentSource, {
+        ...context,
+        checker: context.config.useTsLinkResolution ? context.checker : undefined,
+    });
     if (comment?.getTag("@import") || comment?.getTag("@license")) {
         return;
     }
@@ -70,15 +73,15 @@ function getCommentImpl(commentSource, config, logger, moduleComment, checker, f
     }
     return comment;
 }
-export function getComment(symbol, kind, config, logger, checker, files) {
+export function getComment(symbol, kind, context) {
     const declarations = symbol.declarations || [];
     if (declarations.length &&
         declarations.every((d) => jsDocCommentKinds.includes(d.kind))) {
-        return getJsDocComment(declarations[0], config, logger, checker, files);
+        return getJsDocComment(declarations[0], context);
     }
     const sf = declarations.find(ts.isSourceFile);
     if (sf) {
-        return getFileComment(sf, config, logger, checker, files);
+        return getFileComment(sf, context);
     }
     const isModule = declarations.some((decl) => {
         if (ts.isModuleDeclaration(decl) && ts.isStringLiteral(decl.name)) {
@@ -86,18 +89,18 @@ export function getComment(symbol, kind, config, logger, checker, files) {
         }
         return false;
     });
-    const comment = getCommentImpl(discoverComment(symbol, kind, logger, config.commentStyle, checker, !config.suppressCommentWarningsInDeclarationFiles), config, logger, isModule, checker, files);
+    const comment = getCommentImpl(discoverComment(symbol, kind, context.logger, context.config.commentStyle, context.checker, !context.config.suppressCommentWarningsInDeclarationFiles), isModule, context);
     if (!comment && kind === ReflectionKind.Property) {
-        return getConstructorParamPropertyComment(symbol, config, logger, checker, files);
+        return getConstructorParamPropertyComment(symbol, context);
     }
     return comment;
 }
-export function getNodeComment(node, moduleComment, config, logger, checker, files) {
-    return getCommentImpl(discoverNodeComment(node, config.commentStyle), config, logger, moduleComment, checker, files);
+export function getNodeComment(node, moduleComment, context) {
+    return getCommentImpl(discoverNodeComment(node, context.config.commentStyle), moduleComment, context);
 }
-export function getFileComment(file, config, logger, checker, files) {
-    for (const commentSource of discoverFileComments(file, config.commentStyle)) {
-        const comment = getCommentWithCache(commentSource, config, logger, config.useTsLinkResolution ? checker : undefined, files);
+export function getFileComment(file, context) {
+    for (const commentSource of discoverFileComments(file, context.config.commentStyle)) {
+        const comment = getCommentWithCache(commentSource, context);
         if (comment?.getTag("@license") || comment?.getTag("@import")) {
             continue;
         }
@@ -108,12 +111,12 @@ export function getFileComment(file, config, logger, checker, files) {
         return;
     }
 }
-function getConstructorParamPropertyComment(symbol, config, logger, checker, files) {
+function getConstructorParamPropertyComment(symbol, context) {
     const decl = symbol.declarations?.find(ts.isParameter);
     if (!decl)
         return;
     const ctor = decl.parent;
-    const comment = getSignatureComment(ctor, config, logger, checker, files);
+    const comment = getSignatureComment(ctor, context);
     const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
     if (paramTag) {
         const result = new Comment(paramTag.content);
@@ -121,10 +124,10 @@ function getConstructorParamPropertyComment(symbol, config, logger, checker, fil
         return result;
     }
 }
-export function getSignatureComment(declaration, config, logger, checker, files) {
-    return getCommentImpl(discoverSignatureComment(declaration, checker, config.commentStyle), config, logger, false, checker, files);
+export function getSignatureComment(declaration, context) {
+    return getCommentImpl(discoverSignatureComment(declaration, context.checker, context.config.commentStyle), false, context);
 }
-export function getJsDocComment(declaration, config, logger, checker, files) {
+export function getJsDocComment(declaration, context) {
     const file = declaration.getSourceFile();
     // First, get the whole comment. We know we'll need all of it.
     let parent = declaration.parent;
@@ -143,7 +146,7 @@ export function getJsDocComment(declaration, config, logger, checker, files) {
         ],
         jsDoc: parent,
         inheritedFromParentDeclaration: false,
-    }, config, logger, config.useTsLinkResolution ? checker : undefined, files);
+    }, context);
     // And pull out the tag we actually care about.
     if (ts.isJSDocEnumTag(declaration)) {
         const result = new Comment(comment.getTag("@enum")?.content);
@@ -156,7 +159,7 @@ export function getJsDocComment(declaration, config, logger, checker, files) {
         // We could just put the same comment on everything, but due to how comment parsing works,
         // we'd have to search for any @template with a name starting with the first type parameter's name
         // which feels horribly hacky.
-        logger.warn(i18n.multiple_type_parameters_on_template_tag_unsupported(), declaration);
+        context.logger.warn(i18n.multiple_type_parameters_on_template_tag_unsupported(), declaration);
         return;
     }
     let name;
@@ -176,7 +179,7 @@ export function getJsDocComment(declaration, config, logger, checker, files) {
         // was a comment attached. If there wasn't, then don't error about failing to find
         // a tag because this is unsupported.
         if (!ts.isJSDocTemplateTag(declaration)) {
-            logger.error(i18n.failed_to_find_jsdoc_tag_for_name_0(name), declaration);
+            context.logger.error(i18n.failed_to_find_jsdoc_tag_for_name_0(name), declaration);
         }
     }
     else {

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

@@ -145,7 +145,7 @@ function* lexLineComments2(file, pos, end) {
                 }
                 if (lookahead !== pos + 1) {
                     while (lookahead < end &&
-                        /[a-z0-9]/i.test(file[lookahead])) {
+                        /[a-z0-9-]/i.test(file[lookahead])) {
                         lookahead++;
                     }
                 }

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

@@ -1,10 +1,10 @@
-import type { CommentParserConfig } from "./index.js";
+import type { CommentContextOptionalChecker, CommentParserConfig } from "./index.js";
 import { Comment, type CommentDisplayPart } from "../../models/index.js";
 import type { MinimalSourceFile } from "#utils";
 import { type Token } from "./lexer.js";
 import { FileRegistry } from "../../models/FileRegistry.js";
 import { type Logger } from "#utils";
-export declare function parseComment(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger, files: FileRegistry): Comment;
+export declare function parseComment(tokens: Generator<Token, undefined, undefined>, file: MinimalSourceFile, context: CommentContextOptionalChecker): Comment;
 /**
  * Intended for parsing markdown documents. This only parses code blocks and
  * inline tags outside of code blocks, everything else is text.

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

@@ -40,24 +40,24 @@ function makeLookaheadGenerator(gen) {
         },
     };
 }
-export function parseComment(tokens, config, file, logger, files) {
+export function parseComment(tokens, file, context) {
     const lexer = makeLookaheadGenerator(tokens);
     const tok = lexer.done() || lexer.peek();
     const comment = new Comment();
     comment.sourcePath = file.fileName;
-    comment.summary = blockContent(comment, lexer, config, i18n, warningImpl, files);
+    comment.summary = blockContent(comment, lexer, context.config, i18n, warningImpl, context.files);
     while (!lexer.done()) {
-        comment.blockTags.push(blockTag(comment, lexer, config, i18n, warningImpl, files));
+        comment.blockTags.push(blockTag(comment, lexer, context.config, i18n, warningImpl, context.files));
     }
     const tok2 = tok;
-    postProcessComment(comment, i18n, () => `${nicePath(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`, (message) => logger.warn(message));
+    postProcessComment(comment, i18n, () => `${nicePath(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`, (message) => context.logger.warn(message));
     return comment;
     function warningImpl(message, token) {
-        if (config.suppressCommentWarningsInDeclarationFiles &&
+        if (context.config.suppressCommentWarningsInDeclarationFiles &&
             hasDeclarationFileExtension(file.fileName)) {
             return;
         }
-        logger.warn(message, token.pos, file);
+        context.logger.warn(message, token.pos, file);
     }
 }
 /**

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

@@ -151,7 +151,7 @@ function* lexCommentString2(file) {
                 }
                 if (lookahead !== pos + 1) {
                     while (lookahead < end &&
-                        /[a-z0-9]/i.test(file[lookahead])) {
+                        /[a-z0-9-]/i.test(file[lookahead])) {
                         lookahead++;
                     }
                 }

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

@@ -85,9 +85,11 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
             addRef(reference);
             continue;
         }
-        const tagLink = checkTagLink(data);
-        if (tagLink) {
-            addRef(tagLink);
+        const tagLinks = checkTagLink(data);
+        if (tagLinks.length) {
+            for (const tagLink of tagLinks) {
+                addRef(tagLink);
+            }
             continue;
         }
         const atNewLine = token.text[data.pos] === "\n";
@@ -221,39 +223,111 @@ function checkReference(data) {
     }
 }
 /**
- * Looks for `<a href="./relative">` and `<img src="./relative">`
+ * Looks for `<a href="./relative">`, `<img src="./relative">`, and `<source srcset="./relative">`
  */
 function checkTagLink(data) {
     const { pos, token } = data;
     if (token.text.startsWith("<img ", pos)) {
         data.pos += 4;
-        return checkAttribute(data, "src");
+        return checkAttributes(data, {
+            src: checkAttributeDirectPath,
+            srcset: checkAttributeSrcSet,
+        });
+    }
+    if (token.text.startsWith("<link ", pos)) {
+        data.pos += 4;
+        return checkAttributes(data, {
+            imagesrcset: checkAttributeSrcSet,
+        });
     }
     if (token.text.startsWith("<a ", pos)) {
         data.pos += 3;
-        return checkAttribute(data, "href");
+        return checkAttributes(data, { href: checkAttributeDirectPath });
     }
+    if (token.text.startsWith("<source ", pos)) {
+        data.pos += 8;
+        return checkAttributes(data, {
+            src: checkAttributeDirectPath,
+            srcset: checkAttributeSrcSet,
+        });
+    }
+    return [];
 }
-function checkAttribute(data, attr) {
+function checkAttributes(data, attributes) {
+    const links = [];
     const parser = new HtmlAttributeParser(data.token.text, data.pos);
     while (parser.state !== ParserState.END) {
         if (parser.state === ParserState.BeforeAttributeValue &&
-            parser.currentAttributeName === attr) {
+            Object.prototype.hasOwnProperty.call(attributes, parser.currentAttributeName)) {
             parser.step();
-            if (isRelativePath(parser.currentAttributeValue)) {
-                data.pos = parser.pos;
-                const { target, anchor } = data.files.register(data.sourcePath, parser.currentAttributeValue) || { target: undefined, anchor: undefined };
-                return {
-                    pos: parser.currentAttributeValueStart,
-                    end: parser.currentAttributeValueEnd,
-                    target,
-                    targetAnchor: anchor,
-                };
-            }
-            return;
+            links.push(...attributes[parser.currentAttributeName](data, parser.currentAttributeValue, parser.currentAttributeValueStart, parser.currentAttributeValueEnd));
         }
         parser.step();
     }
+    return links;
+}
+function checkAttributeDirectPath(data, text, pos, end) {
+    if (isRelativePath(text.trim())) {
+        const { target, anchor } = data.files.register(data.sourcePath, text.trim()) || { target: undefined, anchor: undefined };
+        return [{
+                pos,
+                end,
+                target,
+                targetAnchor: anchor,
+            }];
+    }
+    return [];
+}
+// See https://html.spec.whatwg.org/multipage/images.html#srcset-attribute
+function checkAttributeSrcSet(data, text, pos, _end) {
+    const result = [];
+    let textPos = 0;
+    parseImageCandidate();
+    while (textPos < text.length && text[textPos] == ",") {
+        ++textPos;
+        parseImageCandidate();
+    }
+    return result;
+    function parseImageCandidate() {
+        // 1. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos]))
+            ++textPos;
+        // 2. A valid non-empty URL that does not start or end with a comma
+        // TypeDoc: We don't exactly match this, PR welcome! For now, just permit anything
+        // that's not whitespace or a comma
+        const url = text.slice(textPos).match(/^[^\t\r\f\n ,]+/);
+        if (url && isRelativePath(url[0])) {
+            const { target, anchor } = data.files.register(data.sourcePath, url[0]) || { target: undefined, anchor: undefined };
+            result.push({
+                pos: pos + textPos,
+                end: pos + textPos + url[0].length,
+                target,
+                targetAnchor: anchor,
+            });
+        }
+        textPos += url ? url[0].length : 0;
+        // 3. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos]))
+            ++textPos;
+        // 4. Zero or one of the following:
+        {
+            // A width descriptor, consisting of: ASCII whitespace, a valid non-negative integer giving
+            // a number greater than zero representing the width descriptor value, and a U+0077 LATIN
+            // SMALL LETTER W character.
+            const w = text.slice(textPos).match(/^\+?\d+\s*w/);
+            textPos += w ? w[0].length : 0;
+            // A pixel density descriptor, consisting of: ASCII whitespace, a valid floating-point number
+            // giving a number greater than zero representing the pixel density descriptor value, and a
+            // U+0078 LATIN SMALL LETTER X character.
+            if (!w) {
+                const x = text.slice(textPos).match(/^\+?\d+(\.\d+)?([eE][+-]\d+)?\s*x/);
+                textPos += x ? x[0].length : 0;
+            }
+        }
+        // 5. Zero or more ASCII whitespace
+        while (textPos < text.length && /[\t\r\f\n ]/.test(text[textPos]))
+            ++textPos;
+    }
 }
 function isRelativePath(link) {
     // Lots of edge cases encoded right here!

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

@@ -67,6 +67,15 @@ export declare class Context {
      * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
      */
     createSymbolReference(symbol: ts.Symbol, context: Context, name?: string): ReferenceType;
+    /**
+     * Create a stable {@link ReflectionSymbolId} for the provided symbol,
+     * optionally targeting a specific declaration.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     * It might also turn out to be generally useful for other plugin users.
+     */
+    createSymbolId(symbol: ts.Symbol, declaration?: ts.Declaration): import("../models/ReflectionSymbolId.js").ReflectionSymbolId;
     addChild(reflection: DeclarationReflection | DocumentReflection): void;
     shouldIgnore(symbol: ts.Symbol): boolean;
     /**
@@ -81,6 +90,7 @@ export declare class Context {
     getSymbolFromReflection(reflection: Reflection): ts.Symbol | undefined;
     /** @internal */
     setActiveProgram(program: ts.Program | undefined): void;
+    private createCommentContext;
     getComment(symbol: ts.Symbol, kind: ReflectionKind): Comment | undefined;
     getNodeComment(node: ts.Node, moduleComment: boolean): Comment | undefined;
     getFileComment(node: ts.SourceFile): Comment | undefined;

package/dist/lib/converter/context.js

@@ -4,10 +4,10 @@ import { Comment, ContainerReflection, DeclarationReflection, ReferenceType, Ref
 import { isNamedNode } from "./utils/nodes.js";
 import { ConverterEvents } from "./converter-events.js";
 import { resolveAliasedSymbol } from "./utils/symbols.js";
-import { getComment, getFileComment, getJsDocComment, getNodeComment, getSignatureComment } from "./comments/index.js";
+import { getComment, getFileComment, getJsDocComment, getNodeComment, getSignatureComment, } from "./comments/index.js";
 import { getHumanName, getQualifiedName } from "../utils/tsutils.js";
 import { findPackageForPath, normalizePath } from "#node-utils";
-import { createSymbolId } from "./factories/symbol-id.js";
+import { createSymbolIdImpl } from "./factories/symbol-id.js";
 import { removeIf } from "#utils";
 /**
  * The context describes the current state the converter is in.
@@ -185,7 +185,7 @@ export class Context {
      * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
      */
     createSymbolReference(symbol, context, name) {
-        const ref = ReferenceType.createUnresolvedReference(name ?? symbol.name, createSymbolId(symbol), context.project, getQualifiedName(symbol, name ?? symbol.name));
+        const ref = ReferenceType.createUnresolvedReference(name ?? symbol.name, this.createSymbolId(symbol), context.project, getQualifiedName(symbol, name ?? symbol.name));
         ref.refersToTypeParameter = !!(symbol.flags & ts.SymbolFlags.TypeParameter);
         const symbolPath = symbol.declarations?.[0]?.getSourceFile().fileName;
         if (!symbolPath)
@@ -193,6 +193,17 @@ export class Context {
         ref.package = findPackageForPath(symbolPath)?.[0];
         return ref;
     }
+    /**
+     * Create a stable {@link ReflectionSymbolId} for the provided symbol,
+     * optionally targeting a specific declaration.
+     *
+     * @privateRemarks
+     * This is available on Context so that it can be monkey-patched by typedoc-plugin-missing-exports
+     * It might also turn out to be generally useful for other plugin users.
+     */
+    createSymbolId(symbol, declaration) {
+        return createSymbolIdImpl(symbol, declaration);
+    }
     addChild(reflection) {
         if (this.scope instanceof ContainerReflection) {
             this.scope.addChild(reflection);
@@ -211,7 +222,7 @@ export class Context {
     registerReflection(reflection, symbol, filePath) {
         if (symbol) {
             this.reflectionIdToSymbolMap.set(reflection.id, symbol);
-            const id = createSymbolId(symbol);
+            const id = this.createSymbolId(symbol);
             // #2466
             // If we just registered a member of a class or interface, then we need to check if
             // we've registered this symbol before under the wrong parent reflection.
@@ -237,7 +248,7 @@ export class Context {
         }
     }
     getReflectionFromSymbol(symbol) {
-        return this.project.getReflectionFromSymbolId(createSymbolId(symbol));
+        return this.project.getReflectionFromSymbolId(this.createSymbolId(symbol));
     }
     getSymbolFromReflection(reflection) {
         return this.reflectionIdToSymbolMap.get(reflection.id);
@@ -246,20 +257,29 @@ export class Context {
     setActiveProgram(program) {
         this._program = program;
     }
+    createCommentContext() {
+        return {
+            config: this.converter.config,
+            logger: this.logger,
+            checker: this.checker,
+            files: this.project.files,
+            createSymbolId: (s, d) => this.createSymbolId(s, d),
+        };
+    }
     getComment(symbol, kind) {
-        return getComment(symbol, kind, this.converter.config, this.logger, this.checker, this.project.files);
+        return getComment(symbol, kind, this.createCommentContext());
     }
     getNodeComment(node, moduleComment) {
-        return getNodeComment(node, moduleComment, this.converter.config, this.logger, this.checker, this.project.files);
+        return getNodeComment(node, moduleComment, this.createCommentContext());
     }
     getFileComment(node) {
-        return getFileComment(node, this.converter.config, this.logger, this.checker, this.project.files);
+        return getFileComment(node, this.createCommentContext());
     }
     getJsDocComment(declaration) {
-        return getJsDocComment(declaration, this.converter.config, this.logger, this.checker, this.project.files);
+        return getJsDocComment(declaration, this.createCommentContext());
     }
     getSignatureComment(declaration) {
-        return getSignatureComment(declaration, this.converter.config, this.logger, this.checker, this.project.files);
+        return getSignatureComment(declaration, this.createCommentContext());
     }
     shouldInline(symbol, name) {
         if (this.preventInline.has(name))

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

@@ -4,7 +4,6 @@ import { DeclarationReflection, IntrinsicType, ParameterReflection, PredicateTyp
 import { ConverterEvents } from "../converter-events.js";
 import { convertDefaultValue } from "../convert-expression.js";
 import { removeUndefined } from "../utils/reflections.js";
-import { createSymbolId } from "./symbol-id.js";
 export function createSignature(context, kind, signature, symbol, declaration) {
     assert(context.scope instanceof DeclarationReflection);
     declaration ||= signature.getDeclaration();
@@ -17,7 +16,7 @@ export function createSignature(context, kind, signature, symbol, declaration) {
         sigRef.setFlag(ReflectionFlag.Static);
     }
     if (symbol && declaration) {
-        context.project.registerSymbolId(sigRef, createSymbolId(symbol, declaration));
+        context.project.registerSymbolId(sigRef, context.createSymbolId(symbol, declaration));
     }
     let parentReflection = context.scope;
     if (parentReflection.kindOf(ReflectionKind.TypeLiteral) &&

package/dist/lib/converter/factories/symbol-id.d.ts

@@ -1,4 +1,4 @@
 import { ReflectionSymbolId } from "#models";
 import ts from "typescript";
-export declare function createSymbolId(symbol: ts.Symbol, declaration?: ts.Declaration): ReflectionSymbolId;
+export declare function createSymbolIdImpl(symbol: ts.Symbol, declaration?: ts.Declaration): ReflectionSymbolId;
 export declare function addInferredDeclarationMapPaths(opts: ts.CompilerOptions, files: readonly string[]): void;

package/dist/lib/converter/factories/symbol-id.js

@@ -7,7 +7,8 @@ import ts from "typescript";
 const declarationMapCache = new Map();
 let transientCount = 0;
 const transientIds = new WeakMap();
-export function createSymbolId(symbol, declaration) {
+// Don't use this directly, use Context.createSymbolId instead.
+export function createSymbolIdImpl(symbol, declaration) {
     declaration ??= symbol.declarations?.[0];
     const tsSource = declaration?.getSourceFile().fileName ?? "";
     const sourceFileName = resolveDeclarationMaps(tsSource);

package/dist/lib/converter/jsdoc.js

@@ -6,7 +6,6 @@ import ts from "typescript";
 import { DeclarationReflection, IntrinsicType, ReflectionKind, ReflectionType, SignatureReflection, } from "../models/index.js";
 import { ConverterEvents } from "./converter-events.js";
 import { convertParameterNodes, convertTemplateParameterNodes } from "./factories/signature.js";
-import { createSymbolId } from "./factories/symbol-id.js";
 export function convertJsDocAlias(context, symbol, declaration, exportSymbol) {
     if (declaration.typeExpression &&
         ts.isJSDocTypeLiteral(declaration.typeExpression)) {
@@ -57,7 +56,7 @@ function convertJsDocSignature(context, node) {
     context.registerReflection(reflection, symbol);
     context.converter.trigger(ConverterEvents.CREATE_DECLARATION, context, reflection);
     const signature = new SignatureReflection("__type", ReflectionKind.CallSignature, reflection);
-    context.project.registerSymbolId(signature, createSymbolId(symbol, node));
+    context.project.registerSymbolId(signature, context.createSymbolId(symbol, node));
     context.registerReflection(signature, void 0);
     const signatureCtx = rc.withScope(signature);
     reflection.signatures = [signature];

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

@@ -40,7 +40,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
     getReflectionGroups(parent: ContainerReflection, reflections: Array<DeclarationReflection | DocumentReflection>): ReflectionGroup[];
-    getSortFunction(reflection: ContainerReflection): (reflections: (DeclarationReflection | DocumentReflection)[]) => void;
+    getSortFunction(reflection: ContainerReflection): (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     /**
      * Callback used to sort groups by name.
      */

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

@@ -58,7 +58,9 @@ export class ImplementsPlugin extends ConverterComponent {
         });
     }
     analyzeInheritance(project, reflection) {
-        const extendedTypes = filterMap(reflection.extendedTypes ?? [], (type) => {
+        if (!reflection.extendedTypes)
+            return;
+        const extendedTypes = filterMap(reflection.extendedTypes, (type) => {
             return type instanceof ReferenceType &&
                 type.reflection instanceof DeclarationReflection
                 ? type
@@ -73,13 +75,42 @@ export class ImplementsPlugin extends ConverterComponent {
                         ? "overwrites"
                         : "inheritedFrom";
                     for (const [childSig, parentSig] of zip(child.signatures ?? [], parentMember.signatures ?? [])) {
-                        childSig[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentSig, project);
+                        // If we're already pointing at something because TS said we should reference
+                        // it, then don't overwrite the reference.
+                        if (!childSig[key]?.reflection) {
+                            childSig[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentSig, project);
+                        }
+                    }
+                    if (!child[key]?.reflection) {
+                        child[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentMember, project);
                     }
-                    child[key] = ReferenceType.createResolvedReference(`${parent.name}.${parentMember.name}`, parentMember, project);
                     this.handleInheritedComments(child, parentMember);
                 }
             }
         }
+        // #2978, this is very unfortunate. If a child's parent links are broken at this point,
+        // we replace them with an intentionally broken link so that they won't ever be resolved.
+        // This is done because if we don't do it then we run into issues where we have a link which
+        // points to some ReflectionSymbolId which might not exist now, but once we've gone through
+        // serialization/deserialization, might point to an unexpected location. (See the mixin
+        // converter tests, I suspect this might actually be an indication of something else slightly
+        // broken there, but don't want to spend more time with this right now.)
+        for (const child of reflection.children || []) {
+            if (child.inheritedFrom && !child.inheritedFrom.reflection) {
+                child.inheritedFrom = ReferenceType.createBrokenReference(child.inheritedFrom.name, project);
+            }
+            if (child.overwrites && !child.overwrites.reflection) {
+                child.overwrites = ReferenceType.createBrokenReference(child.overwrites.name, project);
+            }
+            for (const childSig of child.getAllSignatures()) {
+                if (childSig.inheritedFrom && !childSig.inheritedFrom.reflection) {
+                    childSig.inheritedFrom = ReferenceType.createBrokenReference(childSig.inheritedFrom.name, project);
+                }
+                if (childSig.overwrites && !childSig.overwrites.reflection) {
+                    childSig.overwrites = ReferenceType.createBrokenReference(childSig.overwrites.name, project);
+                }
+            }
+        }
     }
     onResolveEnd(context) {
         this.resolve(context.project);
@@ -310,8 +341,19 @@ function findProperty(reflection, parent) {
     });
 }
 function createLink(context, reflection, clause, expr, symbol, isInherit) {
-    const project = context.project;
     const name = `${expr.expression.getText()}.${getHumanName(symbol.name)}`;
+    // We should always have rootSymbols, but check just in case. We use the first
+    // symbol here as TypeDoc's models don't have multiple symbols for the parent
+    // reference. This is technically wrong because symbols might be declared in
+    // multiple locations (interface declaration merging), but that's an uncommon
+    // enough use case that it doesn't seem worthwhile to complicate the rest of the
+    // world to deal with it.
+    // Note that we also need to check that the root symbol isn't this symbol.
+    // This seems to happen sometimes when dealing with interface inheritance.
+    const rootSymbols = context.checker.getRootSymbols(symbol);
+    const ref = rootSymbols.length && rootSymbols[0] != symbol
+        ? context.createSymbolReference(rootSymbols[0], context, name)
+        : ReferenceType.createBrokenReference(name, context.project);
     link(reflection);
     link(reflection.getSignature);
     link(reflection.setSignature);
@@ -321,23 +363,19 @@ function createLink(context, reflection, clause, expr, symbol, isInherit) {
     for (const sig of reflection.signatures ?? []) {
         link(sig);
     }
-    // Intentionally create broken links here. These will be replaced with real links during
-    // resolution if we can do so. We create broken links rather than real links because in the
-    // case of an inherited symbol, we'll end up referencing a single symbol ID rather than one
-    // for each class.
     function link(target) {
         if (!target)
             return;
         if (clause.token === ts.SyntaxKind.ImplementsKeyword) {
-            target.implementationOf ??= ReferenceType.createBrokenReference(name, project);
+            target.implementationOf ??= ref;
             return;
         }
         if (isInherit) {
             target.setFlag(ReflectionFlag.Inherited);
-            target.inheritedFrom ??= ReferenceType.createBrokenReference(name, project);
+            target.inheritedFrom ??= ref;
         }
         else {
-            target.overwrites ??= ReferenceType.createBrokenReference(name, project);
+            target.overwrites ??= ref;
         }
     }
 }

package/dist/lib/converter/types.js

@@ -8,7 +8,6 @@ import { convertParameterNodes, convertTypeParameterNodes, createSignature } fro
 import { convertSymbol } from "./symbols.js";
 import { isObjectType, isTypeReference } from "./utils/nodes.js";
 import { removeUndefined } from "./utils/reflections.js";
-import { createSymbolId } from "./factories/symbol-id.js";
 const converters = new Map();
 export function loadConverters() {
     if (converters.size)
@@ -159,7 +158,7 @@ const constructorConverter = {
         if (node.modifiers?.some((m) => m.kind === ts.SyntaxKind.AbstractKeyword)) {
             signature.setFlag(ReflectionFlag.Abstract);
         }
-        context.project.registerSymbolId(signature, createSymbolId(symbol, node));
+        context.project.registerSymbolId(signature, context.createSymbolId(symbol, node));
         context.registerReflection(signature, void 0);
         const signatureCtx = rc.withScope(signature);
         reflection.signatures = [signature];
@@ -208,7 +207,7 @@ const functionTypeConverter = {
         context.registerReflection(reflection, symbol);
         context.converter.trigger(ConverterEvents.CREATE_DECLARATION, context, reflection);
         const signature = new SignatureReflection("__type", ReflectionKind.CallSignature, reflection);
-        context.project.registerSymbolId(signature, createSymbolId(symbol, node));
+        context.project.registerSymbolId(signature, context.createSymbolId(symbol, node));
         context.registerReflection(signature, undefined);
         const signatureCtx = rc.withScope(signature);
         reflection.signatures = [signature];

package/dist/lib/internationalization/locales/en.cjs

@@ -276,6 +276,7 @@ module.exports = {
     favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object",
     option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings",
+    option_0_must_be_an_array_of_string_or_functions: "The '{0}' option must be set to an array of strings/functions",
     option_0_must_be_a_function: "The '{0}' option must be a function",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values`,
     visibility_filters_only_include_0: `visibilityFilters can only include the following non-@ keys: {0}`,

package/dist/lib/internationalization/locales/en.d.cts

@@ -260,6 +260,7 @@ declare const _default: {
     readonly favicon_must_have_one_of_the_following_extensions_0: "Favicon must have one of the following extensions: {0}";
     readonly option_0_must_be_an_object: "The '{0}' option must be a non-array object";
     readonly option_0_must_be_an_array_of_string: "The '{0}' option must be set to an array of strings";
+    readonly option_0_must_be_an_array_of_string_or_functions: "The '{0}' option must be set to an array of strings/functions";
     readonly option_0_must_be_a_function: "The '{0}' option must be a function";
     readonly option_0_must_be_object_with_urls: "{0} must be an object with string labels as keys and URL values";
     readonly visibility_filters_only_include_0: "visibilityFilters can only include the following non-@ keys: {0}";

package/dist/lib/serialization/schema.d.ts

@@ -37,7 +37,7 @@ export declare const SCHEMA_VERSION = "2.0";
 export type ModelToObject<T> = [T] extends [Array<infer U>] ? ModelToObject<U>[] : [
     M.SomeType
 ] extends [T] ? SomeType : _ModelToObject<T>;
-type _ModelToObject<T> = T extends Primitive ? T : Required<T> extends Required<M.ReflectionGroup> ? ReflectionGroup : Required<T> extends Required<M.ReflectionCategory> ? ReflectionCategory : T extends M.ReflectionVariant[keyof M.ReflectionVariant] ? ReflectionVariantMap[T["variant"]] : T extends M.SomeType ? TypeKindMap[T["type"]] : T extends M.Type ? SomeType : T extends M.Comment ? Comment : T extends M.CommentTag ? CommentTag : T extends M.CommentDisplayPart ? CommentDisplayPart : T extends M.SourceReference ? SourceReference : T extends M.FileRegistry ? FileRegistry : never;
+type _ModelToObject<T> = T extends Primitive ? T : Required<T> extends Required<M.ReflectionGroup> ? ReflectionGroup : Required<T> extends Required<M.ReflectionCategory> ? ReflectionCategory : T extends M.ReflectionVariant[keyof M.ReflectionVariant] ? ReflectionVariantMap[T["variant"]] : T extends M.SomeType ? TypeKindMap[T["type"]] : T extends M.Type ? SomeType : T extends M.Comment ? Comment : T extends M.CommentTag ? CommentTag : T extends M.CommentDisplayPart ? CommentDisplayPart : T extends M.SourceReference ? SourceReference : T extends M.FileRegistry ? FileRegistry : T extends M.ReflectionSymbolId ? ReflectionSymbolId : never;
 type Primitive = string | number | undefined | null | boolean;
 type ToSerialized<T> = T extends Primitive ? T : T extends bigint ? {
     value: string;

package/dist/lib/utils/options/declaration.d.ts

@@ -2,8 +2,9 @@ import type { BundledTheme as ShikiTheme } from "@gerrit0/mini-shiki";
 import type { SortStrategy } from "../sort.js";
 import type { EntryPointStrategy } from "../entry-point.js";
 import type { ReflectionKind } from "../../models/kind.js";
-import { type GlobString, type LogLevel, type NeverIfInternal, type NormalizedPath, type NormalizedPathOrModule } from "#utils";
+import { type GlobString, type LogLevel, type NeverIfInternal, type NormalizedPath, type NormalizedPathOrModule, type NormalizedPathOrModuleOrFunction } from "#utils";
 import type { TranslationProxy } from "../../internationalization/internationalization.js";
+import type { Application } from "../../application.js";
 /** @enum */
 export declare const EmitStrategy: {
     readonly both: "both";
@@ -40,7 +41,7 @@ export declare const rootPackageOptions: readonly ["plugin", "packageOptions", "
  * @interface
  */
 export type TypeDocOptions = {
-    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]?: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | GlobString[] ? string[] : TypeDocOptionMap[K] extends NormalizedPath ? string : TypeDocOptionMap[K] extends string | string[] | number | boolean ? TypeDocOptionMap[K] : TypeDocOptionMap[K] extends Record<string, boolean> ? Partial<TypeDocOptionMap[K]> | boolean : keyof TypeDocOptionMap[K] | TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes all TypeDoc specific options as returned by {@link Options.getValue}, this is
@@ -50,7 +51,7 @@ export type TypeDocOptions = {
  * @interface
  */
 export type TypeDocOptionValues = {
-    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | GlobString[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
+    [K in keyof TypeDocOptionMap]: unknown extends TypeDocOptionMap[K] ? unknown : TypeDocOptionMap[K] extends ManuallyValidatedOption<infer ManuallyValidated> ? ManuallyValidated : TypeDocOptionMap[K] extends string | string[] | GlobString[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] | number | boolean | Record<string, boolean> ? TypeDocOptionMap[K] : TypeDocOptionMap[K][keyof TypeDocOptionMap[K]];
 };
 /**
  * Describes TypeDoc options suitable for setting within the `packageOptions` setting.
@@ -78,7 +79,7 @@ export interface TypeDocOptionMap {
     options: NormalizedPath;
     tsconfig: NormalizedPath;
     compilerOptions: unknown;
-    plugin: NormalizedPathOrModule[];
+    plugin: NormalizedPathOrModuleOrFunction[];
     lang: string;
     locales: ManuallyValidatedOption<Record<string, Record<string, string>>>;
     packageOptions: ManuallyValidatedOption<TypeDocPackageOptions>;
@@ -276,7 +277,7 @@ export type JsDocCompatibility = {
 /**
  * Converts a given TypeDoc option key to the type of the declaration expected.
  */
-export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string | NormalizedPath ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends GlobString[] ? GlobArrayDeclarationOption : TypeDocOptionMap[K] extends string[] | NormalizedPath[] | NormalizedPathOrModule[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
+export type KeyToDeclaration<K extends keyof TypeDocOptionMap> = TypeDocOptionMap[K] extends boolean ? BooleanDeclarationOption : TypeDocOptionMap[K] extends string | NormalizedPath ? StringDeclarationOption : TypeDocOptionMap[K] extends number ? NumberDeclarationOption : TypeDocOptionMap[K] extends GlobString[] ? GlobArrayDeclarationOption : TypeDocOptionMap[K] extends string[] | NormalizedPath[] | NormalizedPathOrModule[] | NormalizedPathOrModuleOrFunction[] ? ArrayDeclarationOption : unknown extends TypeDocOptionMap[K] ? MixedDeclarationOption | ObjectDeclarationOption : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown> ? (MixedDeclarationOption & {
     validate(value: unknown, i18n: TranslationProxy): void;
 }) | (ObjectDeclarationOption & {
     validate(value: unknown, i18n: TranslationProxy): void;
@@ -306,20 +307,26 @@ export declare enum ParameterType {
     PathArray = 8,
     /**
      * Resolved according to the config directory if it starts with `.`
+     * @deprecated since 0.28.8, will be removed in 0.29
      */
     ModuleArray = 9,
+    /**
+     * Resolved according to the config directory if it starts with `.`
+     * @internal - only intended for use with the plugin option
+     */
+    PluginArray = 10,
     /**
      * Relative to the config directory.
      */
-    GlobArray = 10,
+    GlobArray = 11,
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    Object = 11,
+    Object = 12,
     /**
      * An object with true/false flags
      */
-    Flags = 12
+    Flags = 13
 }
 export interface DeclarationOptionBase {
     /**
@@ -401,7 +408,7 @@ export interface BooleanDeclarationOption extends DeclarationOptionBase {
     defaultValue?: boolean;
 }
 export interface ArrayDeclarationOption extends DeclarationOptionBase {
-    type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray;
+    type: ParameterType.Array | ParameterType.PathArray | ParameterType.ModuleArray | ParameterType.PluginArray;
     /**
      * If not specified defaults to an empty array.
      */
@@ -482,6 +489,7 @@ export interface ParameterTypeToOptionTypeMap {
     [ParameterType.Array]: string[];
     [ParameterType.PathArray]: NormalizedPath[];
     [ParameterType.ModuleArray]: NormalizedPathOrModule[];
+    [ParameterType.PluginArray]: Array<NormalizedPathOrModule | ((app: Application) => void | Promise<void>)>;
     [ParameterType.GlobArray]: GlobString[];
     [ParameterType.Flags]: Record<string, boolean>;
     [ParameterType.Map]: unknown;

package/dist/lib/utils/options/declaration.js

@@ -112,20 +112,26 @@ export var ParameterType;
     ParameterType[ParameterType["PathArray"] = 8] = "PathArray";
     /**
      * Resolved according to the config directory if it starts with `.`
+     * @deprecated since 0.28.8, will be removed in 0.29
      */
     ParameterType[ParameterType["ModuleArray"] = 9] = "ModuleArray";
+    /**
+     * Resolved according to the config directory if it starts with `.`
+     * @internal - only intended for use with the plugin option
+     */
+    ParameterType[ParameterType["PluginArray"] = 10] = "PluginArray";
     /**
      * Relative to the config directory.
      */
-    ParameterType[ParameterType["GlobArray"] = 10] = "GlobArray";
+    ParameterType[ParameterType["GlobArray"] = 11] = "GlobArray";
     /**
      * An object which partially merges user-set values into the defaults.
      */
-    ParameterType[ParameterType["Object"] = 11] = "Object";
+    ParameterType[ParameterType["Object"] = 12] = "Object";
     /**
      * An object with true/false flags
      */
-    ParameterType[ParameterType["Flags"] = 12] = "Flags";
+    ParameterType[ParameterType["Flags"] = 13] = "Flags";
 })(ParameterType || (ParameterType = {}));
 function toStringArray(value, option) {
     if (Array.isArray(value) && value.every(v => typeof v === "string")) {
@@ -136,6 +142,15 @@ function toStringArray(value, option) {
     }
     throw new Error(i18n.option_0_must_be_an_array_of_string(option.name));
 }
+function toStringOrFunctionArray(value, option) {
+    if (Array.isArray(value) && value.every(v => typeof v === "string" || typeof v === "function")) {
+        return value;
+    }
+    else if (typeof value === "string") {
+        return [value];
+    }
+    throw new Error(i18n.option_0_must_be_an_array_of_string_or_functions(option.name));
+}
 const converters = {
     [ParameterType.String](value, option) {
         // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -183,12 +198,18 @@ const converters = {
         option.validate?.(normalized);
         return normalized;
     },
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     [ParameterType.ModuleArray](value, option, configPath) {
         const strArrValue = toStringArray(value, option);
         const resolved = resolveModulePaths(strArrValue, configPath);
         option.validate?.(resolved);
         return resolved;
     },
+    [ParameterType.PluginArray](value, option, configPath) {
+        const arrayValue = toStringOrFunctionArray(value, option);
+        const resolved = arrayValue.map(plugin => typeof plugin === "function" ? plugin : resolveModulePath(plugin, configPath));
+        return resolved;
+    },
     [ParameterType.GlobArray](value, option, configPath) {
         const toGlobString = (v) => {
             const s = String(v);
@@ -321,12 +342,19 @@ const defaultGetters = {
     [ParameterType.PathArray](option) {
         return (option.defaultValue?.map((value) => normalizePath(resolve(process.cwd(), value))) ?? []);
     },
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     [ParameterType.ModuleArray](option) {
         if (option.defaultValue) {
             return resolveModulePaths(option.defaultValue, process.cwd());
         }
         return [];
     },
+    [ParameterType.PluginArray](option) {
+        if (option.defaultValue) {
+            return resolveModulePaths(option.defaultValue, process.cwd());
+        }
+        return [];
+    },
     [ParameterType.GlobArray](option) {
         return (option.defaultValue ?? []).map(g => createGlobString(normalizePath(process.cwd()), g));
     },
@@ -339,12 +367,13 @@ export function getDefaultValue(option) {
     return getters[option.type ?? ParameterType.String](option);
 }
 function resolveModulePaths(modules, configPath) {
-    return modules.map((path) => {
-        if (path.startsWith(".")) {
-            return normalizePath(resolve(configPath, path));
-        }
-        return normalizePath(path);
-    });
+    return modules.map(path => resolveModulePath(path, configPath));
+}
+function resolveModulePath(path, configPath) {
+    if (path.startsWith(".")) {
+        return normalizePath(resolve(configPath, path));
+    }
+    return normalizePath(path);
 }
 function isTsNumericEnum(map) {
     return Object.values(map).every((key) => map[map[key]] === key);

package/dist/lib/utils/options/readers/arguments.js

@@ -4,7 +4,9 @@ import { i18n } from "#utils";
 const ARRAY_OPTION_TYPES = new Set([
     ParameterType.Array,
     ParameterType.PathArray,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
     ParameterType.ModuleArray,
+    ParameterType.PluginArray,
     ParameterType.GlobArray,
 ]);
 /**

package/dist/lib/utils/options/sources/typedoc.js

@@ -801,7 +801,7 @@ export function addTypeDocOptions(options) {
     options.addDeclaration({
         name: "plugin",
         help: () => i18n.help_plugin(),
-        type: ParameterType.ModuleArray,
+        type: ParameterType.PluginArray,
     });
     options.addDeclaration({
         name: "logLevel",

package/dist/lib/utils/plugins.d.ts

@@ -1,2 +1,3 @@
 import type { Application } from "../application.js";
-export declare function loadPlugins(app: Application, plugins: readonly string[]): Promise<void>;
+import { type NormalizedPathOrModuleOrFunction } from "#utils";
+export declare function loadPlugins(app: Application, plugins: readonly NormalizedPathOrModuleOrFunction[]): Promise<void>;

package/dist/lib/utils/plugins.js

@@ -6,27 +6,33 @@ export async function loadPlugins(app, plugins) {
     for (const plugin of plugins) {
         const pluginDisplay = getPluginDisplayName(plugin);
         try {
-            let instance;
-            // Try importing first to avoid warnings about requiring ESM being experimental.
-            // If that fails due to importing a directory, fall back to require.
-            try {
-                // On Windows, we need to ensure this path is a file path.
-                // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
-                const esmPath = isAbsolute(plugin)
-                    ? pathToFileURL(plugin).toString()
-                    : plugin;
-                instance = await import(esmPath);
+            let initFunction;
+            if (typeof plugin === "function") {
+                initFunction = plugin;
             }
-            catch (error) {
-                if (error.code === "ERR_UNSUPPORTED_DIR_IMPORT") {
-                    // eslint-disable-next-line @typescript-eslint/no-require-imports
-                    instance = require(plugin);
+            else {
+                let instance;
+                // Try importing first to avoid warnings about requiring ESM being experimental.
+                // If that fails due to importing a directory, fall back to require.
+                try {
+                    // On Windows, we need to ensure this path is a file path.
+                    // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
+                    const esmPath = isAbsolute(plugin)
+                        ? pathToFileURL(plugin).toString()
+                        : plugin;
+                    instance = await import(esmPath);
                 }
-                else {
-                    throw error;
+                catch (error) {
+                    if (error.code === "ERR_UNSUPPORTED_DIR_IMPORT") {
+                        // eslint-disable-next-line @typescript-eslint/no-require-imports
+                        instance = require(plugin);
+                    }
+                    else {
+                        throw error;
+                    }
                 }
+                initFunction = instance.load;
             }
-            const initFunction = instance.load;
             if (typeof initFunction === "function") {
                 await initFunction(app);
                 app.logger.info(i18n.loaded_plugin_0(pluginDisplay));
@@ -44,6 +50,9 @@ export async function loadPlugins(app, plugins) {
     }
 }
 function getPluginDisplayName(plugin) {
+    if (typeof plugin === "function") {
+        return plugin.name || "function";
+    }
     const path = nicePath(plugin);
     if (path.startsWith("./node_modules/")) {
         return path.substring("./node_modules/".length);

package/dist/lib/utils-common/path.d.ts

@@ -1,3 +1,4 @@
+import type { Application } from "../application.js";
 /**
  * Represents a normalized path with path separators being `/`
  * On Windows, drives are represented like `C:/Users` for consistency
@@ -15,6 +16,11 @@ export type NormalizedPath = "" | "/" | string & {
 export type NormalizedPathOrModule = NormalizedPath | string & {
     readonly __normPathOrModule: unique symbol;
 };
+/**
+ * Represents either a {@link NormalizedPath} or a Node module name
+ * (e.g. `typedoc-plugin-mdn-links` or `@gerrit0/typedoc-plugin`)
+ */
+export type NormalizedPathOrModuleOrFunction = NormalizedPathOrModule | ((app: Application) => Promise<void> | void);
 /**
  * Represents a glob path configured by a user.
  */

package/dist/lib/utils-common/validation.js

@@ -46,5 +46,5 @@ export function optional(x) {
     return { [opt]: x };
 }
 export function isTagString(x) {
-    return typeof x === "string" && /^@[a-zA-Z][a-zA-Z0-9]*$/.test(x);
+    return typeof x === "string" && /^@[a-z][a-z0-9-]*$/i.test(x);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.28.7",
+  "version": "0.28.8",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {