typedoc - npm Package Compare versions

Comparing version 0.26.1 to 0.26.2

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

@@ -9,10 +9,7 @@ import ts from "typescript";
     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;

dist/lib/converter/comments/discovery.js

@@ -16,2 +16,3 @@ "use strict";
 const assert_1 = require("assert");
+const array_1 = require("../../utils/array");
 const variablePropertyKinds = [
@@ -132,2 +133,3 @@ typescript_1.default.SyntaxKind.PropertyDeclaration,
             jsDoc: findJsDocForComment(node, ranges),
+            inheritedFromParentDeclaration: false,
         };
@@ -146,48 +148,64 @@ });
             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) {
@@ -199,9 +217,13 @@ case 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];
@@ -211,33 +233,33 @@ }
 }
-function discoverSignatureComment(declaration, commentStyle) {
-    const node = declarationToCommentNode(declaration);
-    if (!node) {
-        return;
+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,
+            };
+        }
     }
-    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),
-        };
-    }
 }
@@ -290,3 +312,3 @@ function findJsDocForComment(node, ranges) {
 }
-function declarationToCommentNode(node) {
+function declarationToCommentNodeIgnoringParents(node) {
     // ts.SourceFile is a counterexample
@@ -333,4 +355,51 @@ if (!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;
+    });
+}
 /**
@@ -337,0 +406,0 @@ * Separate comment ranges into arrays so that multiple line comments are kept together

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

@@ -11,8 +11,11 @@ import ts from "typescript";
     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;

dist/lib/converter/comments/index.js

@@ -41,3 +41,6 @@ "use strict";
     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;
     }
@@ -56,2 +59,4 @@ let comment;
     comment.discoveryId = ++commentDiscoveryId;
+    comment.inheritedFromParentDeclaration =
+        discovered.inheritedFromParentDeclaration;
     cache.set(ranges[0].pos, comment);
@@ -62,3 +67,3 @@ commentCache.set(file, cache);
 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")) {
@@ -84,3 +89,3 @@ return;
 }
-function getComment(symbol, kind, config, logger, commentStyle, checker, files) {
+function getComment(symbol, kind, config, logger, checker, files) {
     const declarations = symbol.declarations || [];
@@ -93,3 +98,3 @@ if (declarations.length &&
     if (sf) {
-        return getFileComment(sf, config, logger, commentStyle, checker, files);
+        return getFileComment(sf, config, logger, checker, files);
     }
@@ -102,14 +107,14 @@ const isModule = declarations.some((decl) => {
     });
-    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")) {
@@ -125,3 +130,3 @@ continue;
 }
-function getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker, files) {
+function getConstructorParamPropertyComment(symbol, config, logger, checker, files) {
     const decl = symbol.declarations?.find(typescript_1.default.isParameter);
@@ -131,3 +136,3 @@ if (!decl)
     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");
@@ -140,4 +145,4 @@ if (paramTag) {
 }
-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);
 }
@@ -162,3 +167,4 @@ 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.
@@ -165,0 +171,0 @@ if (typescript_1.default.isJSDocEnumTag(declaration)) {

dist/lib/converter/comments/parser.js

@@ -82,2 +82,6 @@ "use strict";
     function warningImpl(message, token) {
+        if (config.suppressCommentWarningsInDeclarationFiles &&
+            file.fileName.endsWith(".d.ts")) {
+            return;
+        }
         logger.warn(message, token.pos, file);
@@ -102,2 +106,3 @@ }
         },
+        suppressCommentWarningsInDeclarationFiles: true,
     };
@@ -104,0 +109,0 @@ const reentry = new textParser_1.TextParserReentryState();

dist/lib/converter/context.js

@@ -177,15 +177,15 @@ "use strict";
     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);
     }
@@ -192,0 +192,0 @@ withScope(scope) {

dist/lib/converter/converter.d.ts

@@ -59,4 +59,2 @@ import ts from "typescript";
     /** @internal */
-    accessor useTsLinkResolution: boolean;
-    /** @internal */
     accessor preserveLinkText: boolean;
@@ -63,0 +61,0 @@ /** @internal */

dist/lib/converter/converter.js

@@ -76,3 +76,3 @@ "use strict";
 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)({
@@ -114,5 +114,2 @@ name: "converter",
     let _externalSymbolLinkMappings_extraInitializers = [];
-    let _useTsLinkResolution_decorators;
-    let _useTsLinkResolution_initializers = [];
-    let _useTsLinkResolution_extraInitializers = [];
     let _preserveLinkText_decorators;
@@ -153,5 +150,2 @@ let _preserveLinkText_initializers = [];
         /** @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"); }
@@ -177,4 +171,3 @@ set preserveLinkText(value) { __classPrivateFieldSet(this, _Converter_preserveLinkText_accessor_storage, value, "f"); }
             _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)));
@@ -475,2 +468,5 @@ this._config = __runInitializers(this, _maxTypeConversionDepth_extraInitializers);
                 jsDocCompatibility: this.application.options.getValue("jsDocCompatibility"),
+                suppressCommentWarningsInDeclarationFiles: this.application.options.getValue("suppressCommentWarningsInDeclarationFiles"),
+                useTsLinkResolution: this.application.options.getValue("useTsLinkResolution"),
+                commentStyle: this.application.options.getValue("commentStyle"),
             };
@@ -492,3 +488,2 @@ // Can't be included in options because the TSDoc parser blows up if we do.
     _Converter_externalSymbolLinkMappings_accessor_storage = new WeakMap();
-    _Converter_useTsLinkResolution_accessor_storage = new WeakMap();
     _Converter_preserveLinkText_accessor_storage = new WeakMap();
@@ -508,3 +503,2 @@ _Converter_maxTypeConversionDepth_accessor_storage = new WeakMap();
         _externalSymbolLinkMappings_decorators = [(0, utils_1.Option)("externalSymbolLinkMappings")];
-        _useTsLinkResolution_decorators = [(0, utils_1.Option)("useTsLinkResolution")];
         _preserveLinkText_decorators = [(0, utils_1.Option)("preserveLinkText")];
@@ -521,3 +515,2 @@ _maxTypeConversionDepth_decorators = [(0, utils_1.Option)("maxTypeConversionDepth")];
         __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);
@@ -524,0 +517,0 @@ __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);

dist/lib/converter/plugins/CommentPlugin.js

@@ -599,3 +599,3 @@ "use strict";
             moveNestedParamTags(/* in-out */ paramTags, params, comment.sourcePath);
-            if (paramTags.length) {
+            if (!comment.inheritedFromParentDeclaration) {
                 for (const tag of paramTags) {
@@ -602,0 +602,0 @@ this.application.logger.warn(this.application.i18n.signature_0_has_unused_param_with_name_1(signature.getFriendlyFullName(), tag.name ?? "(missing)"));

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

@@ -184,2 +184,9 @@ import type { Reflection } from "../reflections";
     /**
+     * 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.
@@ -186,0 +193,0 @@ */

dist/lib/models/comments/comment.js

@@ -97,2 +97,5 @@ "use strict";
     let _discoveryId_extraInitializers = [];
+    let _inheritedFromParentDeclaration_decorators;
+    let _inheritedFromParentDeclaration_initializers = [];
+    let _inheritedFromParentDeclaration_extraInitializers = [];
     return _a = class Comment {
@@ -305,3 +308,10 @@ /**
                 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;
@@ -319,2 +329,4 @@ this.blockTags = blockTags;
                 comment.sourcePath = this.sourcePath;
+                comment.inheritedFromParentDeclaration =
+                    this.inheritedFromParentDeclaration;
                 return comment;
@@ -401,4 +413,6 @@ }
             _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 });
@@ -405,0 +419,0 @@ })(),

dist/lib/utils/array.d.ts

@@ -0,1 +1,2 @@
+export declare const emptyArray: readonly [];
 /**
@@ -51,1 +52,3 @@ * Inserts an item into an array sorted by priority. If two items have the same priority,
 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[];

dist/lib/utils/array.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyArray = void 0;
 exports.insertPrioritySorted = insertPrioritySorted;
@@ -12,2 +13,5 @@ exports.insertOrderSorted = insertOrderSorted;
 exports.filterMap = filterMap;
+exports.firstDefined = firstDefined;
+exports.filter = filter;
+exports.emptyArray = [];
 /**
@@ -127,1 +131,16 @@ * Inserts an item into an array sorted by priority. If two items have the same priority,
 }
+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;
+}

dist/lib/utils/highlighter.js

@@ -155,3 +155,3 @@ "use strict";
 function isLoadedLanguage(lang) {
-    return highlighter?.supports(lang) ?? false;
+    return lang === "text" || (highlighter?.supports(lang) ?? false);
 }
@@ -158,0 +158,0 @@ function highlight(code, lang) {

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

@@ -158,2 +158,3 @@ import type { BundledTheme as ShikiTheme } from "shiki" with { "resolution-mode": "import" };
     jsDocCompatibility: JsDocCompatibility;
+    suppressCommentWarningsInDeclarationFiles: boolean;
     blockTags: `@${string}`[];
@@ -160,0 +161,0 @@ inlineTags: `@${string}`[];

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

@@ -614,2 +614,7 @@ "use strict";
     options.addDeclaration({
+        name: "suppressCommentWarningsInDeclarationFiles",
+        help: (i18n) => i18n.help_lang(),
+        type: declaration_1.ParameterType.Boolean,
+    });
+    options.addDeclaration({
         name: "commentStyle",
@@ -616,0 +621,0 @@ help: (i18n) => i18n.help_commentStyle(),

package.json

 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "homepage": "https://typedoc.org",
@@ -6,0 +6,0 @@ "exports": {

No alert changes

Improved metrics

Total package byte prevSize

1799477

increased by0.3%

Lines of code

36640

increased by0.33%

No dependency changes