typedoc 0.26.1 → 0.26.2

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,6 +102,7 @@ function parseCommentString(tokens, config, file, logger, files) {
             ignoreUnescapedBraces: true,
             inheritDocTag: true,
         },
+        suppressCommentWarningsInDeclarationFiles: true,
     };
     const reentry = new textParser_1.TextParserReentryState();
     const content = [];

package/dist/lib/converter/context.js

@@ -174,19 +174,19 @@ class Context {
         this._program = program;
     }
     getComment(symbol, kind) {
-        return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+        return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.checker, this.project.files);
     }
     getNodeComment(node, moduleComment) {
-        return (0, comments_1.getNodeComment)(node, moduleComment, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+        return (0, comments_1.getNodeComment)(node, moduleComment, this.converter.config, this.logger, this.checker, this.project.files);
     }
     getFileComment(node) {
-        return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+        return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.checker, this.project.files);
     }
     getJsDocComment(declaration) {
-        return (0, comments_1.getJsDocComment)(declaration, this.converter.config, this.logger, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+        return (0, comments_1.getJsDocComment)(declaration, this.converter.config, this.logger, this.checker, this.project.files);
     }
     getSignatureComment(declaration) {
-        return (0, comments_1.getSignatureComment)(declaration, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+        return (0, comments_1.getSignatureComment)(declaration, this.converter.config, this.logger, this.checker, this.project.files);
     }
     withScope(scope) {
         const context = new Context(this.converter, this.programs, this.project, scope);

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

@@ -56,8 +56,6 @@ export declare class Converter extends ChildableComponent<Application, Converter
     /** @internal */
     accessor externalSymbolLinkMappings: Record<string, Record<string, string>>;
     /** @internal */
-    accessor useTsLinkResolution: boolean;
-    /** @internal */
     accessor preserveLinkText: boolean;
     /** @internal */
     accessor maxTypeConversionDepth: number;

package/dist/lib/converter/converter.js

@@ -73,7 +73,7 @@ const path_1 = require("path");
  * Compiles source files using TypeScript and converts compiler symbols to reflections.
  */
 let Converter = (() => {
-    var _Converter_externalPattern_accessor_storage, _Converter_excludeExternals_accessor_storage, _Converter_excludeNotDocumented_accessor_storage, _Converter_excludePrivate_accessor_storage, _Converter_excludeProtected_accessor_storage, _Converter_excludeReferences_accessor_storage, _Converter_commentStyle_accessor_storage, _Converter_validation_accessor_storage, _Converter_externalSymbolLinkMappings_accessor_storage, _Converter_useTsLinkResolution_accessor_storage, _Converter_preserveLinkText_accessor_storage, _Converter_maxTypeConversionDepth_accessor_storage;
+    var _Converter_externalPattern_accessor_storage, _Converter_excludeExternals_accessor_storage, _Converter_excludeNotDocumented_accessor_storage, _Converter_excludePrivate_accessor_storage, _Converter_excludeProtected_accessor_storage, _Converter_excludeReferences_accessor_storage, _Converter_commentStyle_accessor_storage, _Converter_validation_accessor_storage, _Converter_externalSymbolLinkMappings_accessor_storage, _Converter_preserveLinkText_accessor_storage, _Converter_maxTypeConversionDepth_accessor_storage;
     let _classDecorators = [(0, component_1.Component)({
             name: "converter",
             internal: true,
@@ -110,9 +110,6 @@ let Converter = (() => {
     let _externalSymbolLinkMappings_decorators;
     let _externalSymbolLinkMappings_initializers = [];
     let _externalSymbolLinkMappings_extraInitializers = [];
-    let _useTsLinkResolution_decorators;
-    let _useTsLinkResolution_initializers = [];
-    let _useTsLinkResolution_extraInitializers = [];
     let _preserveLinkText_decorators;
     let _preserveLinkText_initializers = [];
     let _preserveLinkText_extraInitializers = [];
@@ -148,9 +145,6 @@ let Converter = (() => {
         get externalSymbolLinkMappings() { return __classPrivateFieldGet(this, _Converter_externalSymbolLinkMappings_accessor_storage, "f"); }
         set externalSymbolLinkMappings(value) { __classPrivateFieldSet(this, _Converter_externalSymbolLinkMappings_accessor_storage, value, "f"); }
         /** @internal */
-        get useTsLinkResolution() { return __classPrivateFieldGet(this, _Converter_useTsLinkResolution_accessor_storage, "f"); }
-        set useTsLinkResolution(value) { __classPrivateFieldSet(this, _Converter_useTsLinkResolution_accessor_storage, value, "f"); }
-        /** @internal */
         get preserveLinkText() { return __classPrivateFieldGet(this, _Converter_preserveLinkText_accessor_storage, "f"); }
         set preserveLinkText(value) { __classPrivateFieldSet(this, _Converter_preserveLinkText_accessor_storage, value, "f"); }
         /** @internal */
@@ -171,8 +165,7 @@ let Converter = (() => {
             _Converter_commentStyle_accessor_storage.set(this, (__runInitializers(this, _excludeReferences_extraInitializers), __runInitializers(this, _commentStyle_initializers, void 0)));
             _Converter_validation_accessor_storage.set(this, (__runInitializers(this, _commentStyle_extraInitializers), __runInitializers(this, _validation_initializers, void 0)));
             _Converter_externalSymbolLinkMappings_accessor_storage.set(this, (__runInitializers(this, _validation_extraInitializers), __runInitializers(this, _externalSymbolLinkMappings_initializers, void 0)));
-            _Converter_useTsLinkResolution_accessor_storage.set(this, (__runInitializers(this, _externalSymbolLinkMappings_extraInitializers), __runInitializers(this, _useTsLinkResolution_initializers, void 0)));
-            _Converter_preserveLinkText_accessor_storage.set(this, (__runInitializers(this, _useTsLinkResolution_extraInitializers), __runInitializers(this, _preserveLinkText_initializers, void 0)));
+            _Converter_preserveLinkText_accessor_storage.set(this, (__runInitializers(this, _externalSymbolLinkMappings_extraInitializers), __runInitializers(this, _preserveLinkText_initializers, void 0)));
             _Converter_maxTypeConversionDepth_accessor_storage.set(this, (__runInitializers(this, _preserveLinkText_extraInitializers), __runInitializers(this, _maxTypeConversionDepth_initializers, void 0)));
             this._config = __runInitializers(this, _maxTypeConversionDepth_extraInitializers);
             this._externalSymbolResolvers = [];
@@ -468,6 +461,9 @@ let Converter = (() => {
                 inlineTags: new Set(this.application.options.getValue("inlineTags")),
                 modifierTags: new Set(this.application.options.getValue("modifierTags")),
                 jsDocCompatibility: this.application.options.getValue("jsDocCompatibility"),
+                suppressCommentWarningsInDeclarationFiles: this.application.options.getValue("suppressCommentWarningsInDeclarationFiles"),
+                useTsLinkResolution: this.application.options.getValue("useTsLinkResolution"),
+                commentStyle: this.application.options.getValue("commentStyle"),
             };
             // Can't be included in options because the TSDoc parser blows up if we do.
             // TypeDoc supports it as one, so it should always be included here.
@@ -484,7 +480,6 @@ let Converter = (() => {
     _Converter_commentStyle_accessor_storage = new WeakMap();
     _Converter_validation_accessor_storage = new WeakMap();
     _Converter_externalSymbolLinkMappings_accessor_storage = new WeakMap();
-    _Converter_useTsLinkResolution_accessor_storage = new WeakMap();
     _Converter_preserveLinkText_accessor_storage = new WeakMap();
     _Converter_maxTypeConversionDepth_accessor_storage = new WeakMap();
     __setFunctionName(_classThis, "Converter");
@@ -499,7 +494,6 @@ let Converter = (() => {
         _commentStyle_decorators = [(0, utils_1.Option)("commentStyle")];
         _validation_decorators = [(0, utils_1.Option)("validation")];
         _externalSymbolLinkMappings_decorators = [(0, utils_1.Option)("externalSymbolLinkMappings")];
-        _useTsLinkResolution_decorators = [(0, utils_1.Option)("useTsLinkResolution")];
         _preserveLinkText_decorators = [(0, utils_1.Option)("preserveLinkText")];
         _maxTypeConversionDepth_decorators = [(0, utils_1.Option)("maxTypeConversionDepth")];
         __esDecorate(_classThis, null, _externalPattern_decorators, { kind: "accessor", name: "externalPattern", static: false, private: false, access: { has: obj => "externalPattern" in obj, get: obj => obj.externalPattern, set: (obj, value) => { obj.externalPattern = value; } }, metadata: _metadata }, _externalPattern_initializers, _externalPattern_extraInitializers);
@@ -511,7 +505,6 @@ let Converter = (() => {
         __esDecorate(_classThis, null, _commentStyle_decorators, { kind: "accessor", name: "commentStyle", static: false, private: false, access: { has: obj => "commentStyle" in obj, get: obj => obj.commentStyle, set: (obj, value) => { obj.commentStyle = value; } }, metadata: _metadata }, _commentStyle_initializers, _commentStyle_extraInitializers);
         __esDecorate(_classThis, null, _validation_decorators, { kind: "accessor", name: "validation", static: false, private: false, access: { has: obj => "validation" in obj, get: obj => obj.validation, set: (obj, value) => { obj.validation = value; } }, metadata: _metadata }, _validation_initializers, _validation_extraInitializers);
         __esDecorate(_classThis, null, _externalSymbolLinkMappings_decorators, { kind: "accessor", name: "externalSymbolLinkMappings", static: false, private: false, access: { has: obj => "externalSymbolLinkMappings" in obj, get: obj => obj.externalSymbolLinkMappings, set: (obj, value) => { obj.externalSymbolLinkMappings = value; } }, metadata: _metadata }, _externalSymbolLinkMappings_initializers, _externalSymbolLinkMappings_extraInitializers);
-        __esDecorate(_classThis, null, _useTsLinkResolution_decorators, { kind: "accessor", name: "useTsLinkResolution", static: false, private: false, access: { has: obj => "useTsLinkResolution" in obj, get: obj => obj.useTsLinkResolution, set: (obj, value) => { obj.useTsLinkResolution = value; } }, metadata: _metadata }, _useTsLinkResolution_initializers, _useTsLinkResolution_extraInitializers);
         __esDecorate(_classThis, null, _preserveLinkText_decorators, { kind: "accessor", name: "preserveLinkText", static: false, private: false, access: { has: obj => "preserveLinkText" in obj, get: obj => obj.preserveLinkText, set: (obj, value) => { obj.preserveLinkText = value; } }, metadata: _metadata }, _preserveLinkText_initializers, _preserveLinkText_extraInitializers);
         __esDecorate(_classThis, null, _maxTypeConversionDepth_decorators, { kind: "accessor", name: "maxTypeConversionDepth", static: false, private: false, access: { has: obj => "maxTypeConversionDepth" in obj, get: obj => obj.maxTypeConversionDepth, set: (obj, value) => { obj.maxTypeConversionDepth = value; } }, metadata: _metadata }, _maxTypeConversionDepth_initializers, _maxTypeConversionDepth_extraInitializers);
         __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);

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

@@ -596,7 +596,7 @@ let CommentPlugin = (() => {
             const paramTags = comment.blockTags.filter((tag) => tag.tag === "@param");
             (0, utils_1.removeIf)(paramTags, (tag) => params.some((param) => param.name === tag.name));
             moveNestedParamTags(/* in-out */ paramTags, params, comment.sourcePath);
-            if (paramTags.length) {
+            if (!comment.inheritedFromParentDeclaration) {
                 for (const tag of paramTags) {
                     this.application.logger.warn(this.application.i18n.signature_0_has_unused_param_with_name_1(signature.getFriendlyFullName(), tag.name ?? "(missing)"));
                 }

package/dist/lib/models/comments/comment.d.ts

@@ -180,6 +180,13 @@ export declare class Comment {
      * @internal
      */
     discoveryId?: number;
+    /**
+     * If the comment was inherited from a different "parent" declaration
+     * (see #2545), then it is desirable to know this as any `@param` tags
+     * which do not apply should not cause warnings. This is not serialized,
+     * and only set when the comment was created from a `ts.CommentRange`.
+     */
+    inheritedFromParentDeclaration?: boolean;
     /**
      * Creates a new Comment instance.
      */

package/dist/lib/models/comments/comment.js

@@ -94,6 +94,9 @@ let Comment = (() => {
     let _discoveryId_decorators;
     let _discoveryId_initializers = [];
     let _discoveryId_extraInitializers = [];
+    let _inheritedFromParentDeclaration_decorators;
+    let _inheritedFromParentDeclaration_initializers = [];
+    let _inheritedFromParentDeclaration_extraInitializers = [];
     return _a = class Comment {
             /**
              * Debugging utility for combining parts into a simple string. Not suitable for
@@ -301,7 +304,14 @@ let Comment = (() => {
                  * @internal
                  */
                 this.discoveryId = (__runInitializers(this, _sourcePath_extraInitializers), __runInitializers(this, _discoveryId_initializers, void 0));
-                __runInitializers(this, _discoveryId_extraInitializers);
+                /**
+                 * If the comment was inherited from a different "parent" declaration
+                 * (see #2545), then it is desirable to know this as any `@param` tags
+                 * which do not apply should not cause warnings. This is not serialized,
+                 * and only set when the comment was created from a `ts.CommentRange`.
+                 */
+                this.inheritedFromParentDeclaration = (__runInitializers(this, _discoveryId_extraInitializers), __runInitializers(this, _inheritedFromParentDeclaration_initializers, void 0));
+                __runInitializers(this, _inheritedFromParentDeclaration_extraInitializers);
                 this.summary = summary;
                 this.blockTags = blockTags;
                 this.modifierTags = modifierTags;
@@ -314,6 +324,8 @@ let Comment = (() => {
                 const comment = new _a(_a.cloneDisplayParts(this.summary), this.blockTags.map((tag) => tag.clone()), new Set(this.modifierTags));
                 comment.discoveryId = this.discoveryId;
                 comment.sourcePath = this.sourcePath;
+                comment.inheritedFromParentDeclaration =
+                    this.inheritedFromParentDeclaration;
                 return comment;
             }
             /**
@@ -395,8 +407,10 @@ let Comment = (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
             _sourcePath_decorators = [general_1.NonEnumerable];
             _discoveryId_decorators = [general_1.NonEnumerable];
+            _inheritedFromParentDeclaration_decorators = [general_1.NonEnumerable];
             __esDecorate(null, null, _sourcePath_decorators, { kind: "field", name: "sourcePath", static: false, private: false, access: { has: obj => "sourcePath" in obj, get: obj => obj.sourcePath, set: (obj, value) => { obj.sourcePath = value; } }, metadata: _metadata }, _sourcePath_initializers, _sourcePath_extraInitializers);
             __esDecorate(null, null, _discoveryId_decorators, { kind: "field", name: "discoveryId", static: false, private: false, access: { has: obj => "discoveryId" in obj, get: obj => obj.discoveryId, set: (obj, value) => { obj.discoveryId = value; } }, metadata: _metadata }, _discoveryId_initializers, _discoveryId_extraInitializers);
+            __esDecorate(null, null, _inheritedFromParentDeclaration_decorators, { kind: "field", name: "inheritedFromParentDeclaration", static: false, private: false, access: { has: obj => "inheritedFromParentDeclaration" in obj, get: obj => obj.inheritedFromParentDeclaration, set: (obj, value) => { obj.inheritedFromParentDeclaration = value; } }, metadata: _metadata }, _inheritedFromParentDeclaration_initializers, _inheritedFromParentDeclaration_extraInitializers);
             if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         })(),
         _a;

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

@@ -1,3 +1,4 @@
+export declare const emptyArray: readonly [];
 /**
  * Inserts an item into an array sorted by priority. If two items have the same priority,
  * the item will be inserted later will be placed earlier in the array.
@@ -48,3 +49,5 @@ export declare function zip<T extends Iterable<any>[]>(...args: T): Iterable<{
     [K in keyof T]: T[K] extends Iterable<infer U> ? U : T[K];
 }>;
 export declare function filterMap<T, U>(iter: Iterable<T>, fn: (item: T) => U | undefined): U[];
+export declare function firstDefined<T, U>(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined;
+export declare function filter<T>(array: readonly T[] | undefined, predicate: (value: T, index: number, array: readonly T[]) => boolean): readonly T[];

package/dist/lib/utils/array.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyArray = void 0;
 exports.insertPrioritySorted = insertPrioritySorted;
 exports.insertOrderSorted = insertOrderSorted;
 exports.binaryFindPartition = binaryFindPartition;
@@ -9,6 +10,9 @@ exports.unique = unique;
 exports.partition = partition;
 exports.zip = zip;
 exports.filterMap = filterMap;
+exports.firstDefined = firstDefined;
+exports.filter = filter;
+exports.emptyArray = [];
 /**
  * Inserts an item into an array sorted by priority. If two items have the same priority,
  * the item will be inserted later will be placed earlier in the array.
@@ -123,3 +127,18 @@ function filterMap(iter, fn) {
     }
     return result;
 }
+function firstDefined(array, callback) {
+    if (array === undefined) {
+        return undefined;
+    }
+    for (let i = 0; i < array.length; i++) {
+        const result = callback(array[i], i);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    return undefined;
+}
+function filter(array, predicate) {
+    return array ? array.filter(predicate) : exports.emptyArray;
+}

package/dist/lib/utils/highlighter.js

@@ -152,7 +152,7 @@ function getSupportedThemes() {
     return supportedThemes;
 }
 function isLoadedLanguage(lang) {
-    return highlighter?.supports(lang) ?? false;
+    return lang === "text" || (highlighter?.supports(lang) ?? false);
 }
 function highlight(code, lang) {
     (0, assert_1.ok)(highlighter, "Tried to highlight with an uninitialized highlighter");

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

@@ -155,6 +155,7 @@ export interface TypeDocOptionMap {
     useTsLinkResolution: boolean;
     preserveLinkText: boolean;
     jsDocCompatibility: JsDocCompatibility;
+    suppressCommentWarningsInDeclarationFiles: boolean;
     blockTags: `@${string}`[];
     inlineTags: `@${string}`[];
     modifierTags: `@${string}`[];

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

@@ -610,6 +610,11 @@ function addTypeDocOptions(options) {
             ignoreUnescapedBraces: true,
         },
     });
+    options.addDeclaration({
+        name: "suppressCommentWarningsInDeclarationFiles",
+        help: (i18n) => i18n.help_lang(),
+        type: declaration_1.ParameterType.Boolean,
+    });
     options.addDeclaration({
         name: "commentStyle",
         help: (i18n) => i18n.help_commentStyle(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "homepage": "https://typedoc.org",
   "exports": {
     ".": "./dist/index.js",