typedoc 0.25.13 → 0.26.0-beta.0

package/dist/lib/converter/converter.js

@@ -208,6 +208,7 @@ let Converter = (() => {
             const project = new index_1.ProjectReflection(this.application.options.getValue("name"));
             const context = new context_1.Context(this, programs, project);
             this.trigger(Converter.EVENT_BEGIN, context);
+            this.addProjectDocuments(project);
             this.compile(entryPoints, context);
             this.resolve(context);
             this.trigger(Converter.EVENT_END, context);
@@ -215,6 +216,17 @@ let Converter = (() => {
             return project;
         }
         /** @internal */
+        addProjectDocuments(project) {
+            const projectDocuments = (0, utils_1.getDocumentEntryPoints)(this.application.logger, this.application.options);
+            for (const { displayName, path } of projectDocuments) {
+                const file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
+                const { content, frontmatter } = this.parseRawComment(file);
+                const docRefl = new index_1.DocumentReflection(displayName, project, content, frontmatter);
+                project.addChild(docRefl);
+                project.registerReflection(docRefl);
+            }
+        }
+        /** @internal */
         convertSymbol(context, symbol, exportSymbol) {
             (0, symbols_1.convertSymbol)(context, symbol, exportSymbol);
         }
@@ -232,7 +244,7 @@ let Converter = (() => {
          * Parse the given file into a comment. Intended to be used with markdown files.
          */
         parseRawComment(file) {
-            return (0, parser_1.parseComment)((0, rawLexer_1.lexCommentString)(file.text), this.config, file, this.application.logger);
+            return (0, parser_1.parseCommentString)((0, rawLexer_1.lexCommentString)(file.text), this.config, file, this.application.logger);
         }
         /**
          * Adds a new resolver that the theme can use to try to figure out how to link to a symbol declared
@@ -314,15 +326,8 @@ let Converter = (() => {
                 }
                 if (entryPoint.readmeFile) {
                     const readme = (0, utils_1.readFile)(entryPoint.readmeFile);
-                    const comment = this.parseRawComment(new utils_1.MinimalSourceFile(readme, entryPoint.readmeFile));
-                    if (comment.blockTags.length || comment.modifierTags.size) {
-                        const ignored = [
-                            ...comment.blockTags.map((tag) => tag.tag),
-                            ...comment.modifierTags,
-                        ];
-                        context.logger.warn(`Block and modifier tags will be ignored within the readme:\n\t${ignored.join("\n\t")}`);
-                    }
-                    reflection.readme = comment.summary;
+                    const { content } = this.parseRawComment(new utils_1.MinimalSourceFile(readme, entryPoint.readmeFile));
+                    reflection.readme = content;
                 }
                 reflection.packageVersion = entryPoint.version;
                 context.finalizeDeclarationReflection(reflection);
@@ -511,9 +516,7 @@ function getSymbolForModuleLike(context, node) {
     const sourceFile = node.getSourceFile();
     const globalSymbols = context.checker
         .getSymbolsInScope(node, typescript_1.default.SymbolFlags.ModuleMember)
-        .filter((s) => s
-        .getDeclarations()
-        ?.some((d) => d.getSourceFile() === sourceFile));
+        .filter((s) => s.getDeclarations()?.some((d) => d.getSourceFile() === sourceFile));
     // Detect declaration files with declare module "foo" as their only export
     // and lift that up one level as the source file symbol
     if (globalSymbols.length === 1 &&

package/dist/lib/converter/factories/index-signature.d.ts

@@ -1,3 +1,3 @@
 import ts from "typescript";
 import type { Context } from "../context";
-export declare function convertIndexSignature(context: Context, symbol: ts.Symbol): void;
+export declare function convertIndexSignatures(context: Context, symbol: ts.Symbol): void;

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

@@ -3,33 +3,30 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertIndexSignature = void 0;
+exports.convertIndexSignatures = convertIndexSignatures;
 const assert_1 = __importDefault(require("assert"));
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../../models");
 const converter_events_1 = require("../converter-events");
-function convertIndexSignature(context, symbol) {
+function convertIndexSignatures(context, symbol) {
     (0, assert_1.default)(context.scope instanceof models_1.DeclarationReflection);
     const indexSymbol = symbol.members?.get("__index");
-    if (indexSymbol) {
-        // Right now TypeDoc models don't have a way to distinguish between string
-        // and number index signatures... { [x: string]: 1 | 2; [x: number]: 2 }
-        // will be misrepresented.
-        const indexDeclaration = indexSymbol.getDeclarations()?.[0];
-        (0, assert_1.default)(indexDeclaration &&
-            typescript_1.default.isIndexSignatureDeclaration(indexDeclaration));
+    if (!indexSymbol)
+        return;
+    for (const indexDeclaration of indexSymbol.getDeclarations() || []) {
+        (0, assert_1.default)(typescript_1.default.isIndexSignatureDeclaration(indexDeclaration));
         const param = indexDeclaration.parameters[0];
         (0, assert_1.default)(param && typescript_1.default.isParameter(param));
         const index = new models_1.SignatureReflection("__index", models_1.ReflectionKind.IndexSignature, context.scope);
-        index.comment = context.getComment(indexSymbol, index.kind);
+        index.comment = context.getNodeComment(indexDeclaration, index.kind);
         index.parameters = [
             new models_1.ParameterReflection(param.name.getText(), models_1.ReflectionKind.Parameter, index),
         ];
         index.parameters[0].type = context.converter.convertType(context.withScope(index.parameters[0]), param.type);
         index.type = context.converter.convertType(context.withScope(index), indexDeclaration.type);
         context.registerReflection(index, indexSymbol);
-        context.scope.indexSignature = index;
+        context.scope.indexSignatures ||= [];
+        context.scope.indexSignatures.push(index);
         context.trigger(converter_events_1.ConverterEvents.CREATE_SIGNATURE, index, indexDeclaration);
     }
 }
-exports.convertIndexSignature = convertIndexSignature;

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

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { ParameterReflection, Reflection, ReflectionKind, SignatureReflection, TypeParameterReflection } from "../../models";
+import { ParameterReflection, type Reflection, ReflectionKind, SignatureReflection, TypeParameterReflection } from "../../models";
 import type { Context } from "../context";
 export declare function createSignature(context: Context, kind: ReflectionKind.CallSignature | ReflectionKind.ConstructorSignature | ReflectionKind.GetSignature | ReflectionKind.SetSignature, signature: ts.Signature, symbol: ts.Symbol | undefined, declaration?: ts.SignatureDeclaration | ts.JSDocSignature): void;
 /**

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

@@ -3,7 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertTemplateParameterNodes = exports.createTypeParamReflection = exports.convertTypeParameterNodes = exports.convertParameterNodes = exports.createConstructSignatureWithType = exports.createSignature = void 0;
+exports.createSignature = createSignature;
+exports.createConstructSignatureWithType = createConstructSignatureWithType;
+exports.convertParameterNodes = convertParameterNodes;
+exports.convertTypeParameterNodes = convertTypeParameterNodes;
+exports.createTypeParamReflection = createTypeParamReflection;
+exports.convertTemplateParameterNodes = convertTemplateParameterNodes;
 const typescript_1 = __importDefault(require("typescript"));
 const assert_1 = __importDefault(require("assert"));
 const models_1 = require("../../models");
@@ -34,11 +39,11 @@ function createSignature(context, kind, signature, symbol, declaration) {
         parentReflection.parent instanceof models_1.DeclarationReflection) {
         parentReflection = parentReflection.parent;
     }
-    if (declaration &&
-        (!parentReflection.comment ||
-            !(parentReflection.conversionFlags &
-                models_1.ConversionFlags.VariableOrPropertySource))) {
-        sigRef.comment = context.getSignatureComment(declaration);
+    if (declaration) {
+        const sigComment = context.getSignatureComment(declaration);
+        if (parentReflection.comment?.discoveryId !== sigComment?.discoveryId) {
+            sigRef.comment = sigComment;
+        }
     }
     sigRef.typeParameters = convertTypeParameters(sigRefCtx, sigRef, signature.typeParameters);
     const parameterSymbols = signature.thisParameter
@@ -76,7 +81,6 @@ function createSignature(context, kind, signature, symbol, declaration) {
     }
     context.converter.trigger(converter_events_1.ConverterEvents.CREATE_SIGNATURE, context, sigRef, declaration, signature);
 }
-exports.createSignature = createSignature;
 /**
  * Special cased constructor factory for functions tagged with `@class`
  */
@@ -95,7 +99,6 @@ function createConstructSignatureWithType(context, signature, classType) {
     context.scope.signatures.push(sigRef);
     context.converter.trigger(converter_events_1.ConverterEvents.CREATE_SIGNATURE, context, sigRef, declaration, signature);
 }
-exports.createConstructSignatureWithType = createConstructSignatureWithType;
 function convertParameters(context, sigRef, parameters, parameterNodes) {
     return parameters.map((param, i) => {
         const declaration = param.valueDeclaration;
@@ -179,7 +182,6 @@ function convertParameterNodes(context, sigRef, parameters) {
         return paramRefl;
     });
 }
-exports.convertParameterNodes = convertParameterNodes;
 function checkForDestructuredParameterDefaults(param, decl) {
     if (!decl || !typescript_1.default.isParameter(decl))
         return;
@@ -226,7 +228,6 @@ function convertTypeParameters(context, parent, parameters) {
 function convertTypeParameterNodes(context, parameters) {
     return parameters?.map((param) => createTypeParamReflection(param, context));
 }
-exports.convertTypeParameterNodes = convertTypeParameterNodes;
 function createTypeParamReflection(param, context) {
     const paramRefl = new models_1.TypeParameterReflection(param.name.text, context.scope, getVariance(param.modifiers));
     const paramScope = context.withScope(paramRefl);
@@ -246,7 +247,6 @@ function createTypeParamReflection(param, context) {
     context.trigger(converter_events_1.ConverterEvents.CREATE_TYPE_PARAMETER, paramRefl, param);
     return paramRefl;
 }
-exports.createTypeParamReflection = createTypeParamReflection;
 function convertTemplateParameterNodes(context, nodes) {
     return nodes?.flatMap((node) => {
         return node.typeParameters.map((param, index) => {
@@ -271,7 +271,6 @@ function convertTemplateParameterNodes(context, nodes) {
         });
     });
 }
-exports.convertTemplateParameterNodes = convertTemplateParameterNodes;
 function getVariance(modifiers) {
     const hasIn = modifiers?.some((mod) => mod.kind === typescript_1.default.SyntaxKind.InKeyword);
     const hasOut = modifiers?.some((mod) => mod.kind === typescript_1.default.SyntaxKind.OutKeyword);

package/dist/lib/converter/jsdoc.js

@@ -6,7 +6,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertJsDocCallback = exports.convertJsDocAlias = void 0;
+exports.convertJsDocAlias = convertJsDocAlias;
+exports.convertJsDocCallback = convertJsDocCallback;
 const assert_1 = require("assert");
 const typescript_1 = __importDefault(require("typescript"));
 const models_1 = require("../models");
@@ -33,7 +34,6 @@ function convertJsDocAlias(context, symbol, declaration, exportSymbol) {
     convertTemplateParameters(context.withScope(reflection), declaration.parent);
     context.finalizeDeclarationReflection(reflection);
 }
-exports.convertJsDocAlias = convertJsDocAlias;
 function convertJsDocCallback(context, symbol, declaration, exportSymbol) {
     const alias = context.createDeclarationReflection(models_1.ReflectionKind.TypeAlias, symbol, exportSymbol);
     alias.comment = context.getJsDocComment(declaration);
@@ -42,7 +42,6 @@ function convertJsDocCallback(context, symbol, declaration, exportSymbol) {
     alias.type = convertJsDocSignature(ac, declaration.typeExpression);
     convertTemplateParameters(ac, declaration.parent);
 }
-exports.convertJsDocCallback = convertJsDocCallback;
 function convertJsDocInterface(context, declaration, symbol, exportSymbol) {
     const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Interface, symbol, exportSymbol);
     reflection.comment = context.getJsDocComment(declaration);

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

@@ -1,4 +1,4 @@
-import { DeclarationReflection } from "../../models";
+import { type DeclarationReflection, type DocumentReflection } from "../../models";
 import { ConverterComponent } from "../components";
 /**
  * A handler that sorts and categorizes the found reflections in the resolving phase.
@@ -6,7 +6,7 @@ import { ConverterComponent } from "../components";
  * The handler sets the ´category´ property of all reflections.
  */
 export declare class CategoryPlugin extends ConverterComponent {
-    sortFunction: (reflections: DeclarationReflection[]) => void;
+    sortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     accessor defaultCategory: string;
     accessor categoryOrder: string[];
     accessor categorizeByGroup: boolean;
@@ -58,5 +58,5 @@ export declare class CategoryPlugin extends ConverterComponent {
      * @returns The sorting weight.
      */
     private static sortCatCallback;
-    static getCategories(reflection: DeclarationReflection): Set<string>;
+    static getCategories(reflection: DeclarationReflection | DocumentReflection): Set<string>;
 }

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

@@ -138,8 +138,7 @@ let CategoryPlugin = (() => {
             }
             this.usedBoosts.clear();
             if (unusedBoosts.size) {
-                context.logger.warn(`Not all categories specified in searchCategoryBoosts were used in the documentation.` +
-                    ` The unused categories were:\n\t${Array.from(unusedBoosts).join("\n\t")}`);
+                context.logger.warn(context.i18n.not_all_search_category_boosts_used_0(Array.from(unusedBoosts).join("\n\t")));
             }
         }
         categorize(obj) {
@@ -218,7 +217,7 @@ let CategoryPlugin = (() => {
                             cat.description = body;
                         }
                         else {
-                            this.application.logger.warn(`Comment for ${parent.getFriendlyFullName()} includes @categoryDescription for "${header}", but no child is placed in that category.`);
+                            this.application.logger.warn(this.application.i18n.comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group(parent.getFriendlyFullName(), header));
                         }
                         return true;
                     }
@@ -242,14 +241,20 @@ let CategoryPlugin = (() => {
         extractCategories(reflection) {
             const categories = CategoryPlugin.getCategories(reflection);
             reflection.comment?.removeTags("@category");
-            for (const sig of reflection.getNonIndexSignatures()) {
-                sig.comment?.removeTags("@category");
-            }
-            if (reflection.type?.type === "reflection") {
-                reflection.type.declaration.comment?.removeTags("@category");
-                for (const sig of reflection.type.declaration.getNonIndexSignatures()) {
+            if (reflection.isDeclaration()) {
+                for (const sig of reflection.getNonIndexSignatures()) {
                     sig.comment?.removeTags("@category");
                 }
+                if (reflection.type?.type === "reflection") {
+                    reflection.type.declaration.comment?.removeTags("@category");
+                    for (const sig of reflection.type.declaration.getNonIndexSignatures()) {
+                        sig.comment?.removeTags("@category");
+                    }
+                }
+            }
+            if (reflection.isDocument() && "category" in reflection.frontmatter) {
+                categories.add(String(reflection.frontmatter["category"]));
+                delete reflection.frontmatter["category"];
             }
             categories.delete("");
             for (const cat of categories) {
@@ -300,14 +305,16 @@ let CategoryPlugin = (() => {
                 }
             }
             discoverCategories(reflection.comment);
-            for (const sig of reflection.getNonIndexSignatures()) {
-                discoverCategories(sig.comment);
-            }
-            if (reflection.type?.type === "reflection") {
-                discoverCategories(reflection.type.declaration.comment);
-                for (const sig of reflection.type.declaration.getNonIndexSignatures()) {
+            if (reflection.isDeclaration()) {
+                for (const sig of reflection.getNonIndexSignatures()) {
                     discoverCategories(sig.comment);
                 }
+                if (reflection.type?.type === "reflection") {
+                    discoverCategories(reflection.type.declaration.comment);
+                    for (const sig of reflection.type.declaration.getNonIndexSignatures()) {
+                        discoverCategories(sig.comment);
+                    }
+                }
             }
             categories.delete("");
             return categories;

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

@@ -112,7 +112,7 @@ export declare class CommentPlugin extends ConverterComponent {
      * @param reflection  The reflection that is currently resolved.
      */
     private onResolve;
-    private moveCommentToSignatures;
+    private moveSignatureParamComments;
     private removeExcludedTags;
     /**
      * Determines whether or not a reflection has been hidden

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

@@ -281,6 +281,7 @@ let CommentPlugin = (() => {
                 }
                 if (tag) {
                     reflection.comment = new models_1.Comment(tag.content);
+                    reflection.comment.sourcePath = comment.sourcePath;
                     (0, utils_1.removeIfPresent)(comment.blockTags, tag);
                 }
             }
@@ -366,80 +367,67 @@ let CommentPlugin = (() => {
             if (reflection.comment) {
                 if (reflection.comment.label &&
                     !/[A-Z_][A-Z0-9_]/.test(reflection.comment.label)) {
-                    context.logger.warn(`The label "${reflection.comment.label}" for ${reflection.getFriendlyFullName()} cannot be referenced with a declaration reference. ` +
-                        `Labels may only contain A-Z, 0-9, and _, and may not start with a number.`);
+                    context.logger.warn(context.i18n.label_0_for_1_cannot_be_referenced(reflection.comment.label, reflection.getFriendlyFullName()));
                 }
                 mergeSeeTags(reflection.comment);
                 movePropertyTags(reflection.comment, reflection);
             }
-            if (!(reflection instanceof models_1.DeclarationReflection)) {
-                return;
-            }
-            if (reflection.type instanceof models_1.ReflectionType) {
-                this.moveCommentToSignatures(reflection, reflection.type.declaration.getNonIndexSignatures());
+            if (reflection instanceof models_1.DeclarationReflection && reflection.comment) {
+                let sigs;
+                if (reflection.type instanceof models_1.ReflectionType) {
+                    sigs = reflection.type.declaration.getNonIndexSignatures();
+                }
+                else {
+                    sigs = reflection.getNonIndexSignatures();
+                }
+                // For variables and properties, the symbol might own the comment but we might also
+                // have @param and @returns comments for an owned signature. Only do this if there is
+                // exactly one signature as otherwise we have no hope of doing validation right.
+                if (sigs.length === 1 && !sigs[0].comment) {
+                    this.moveSignatureParamComments(sigs[0], reflection.comment);
+                    const returnsTag = reflection.comment.getTag("@returns");
+                    if (returnsTag) {
+                        sigs[0].comment = new models_1.Comment();
+                        sigs[0].comment.sourcePath = reflection.comment.sourcePath;
+                        sigs[0].comment.blockTags.push(returnsTag);
+                        reflection.comment.removeTags("@returns");
+                    }
+                }
             }
-            else {
-                this.moveCommentToSignatures(reflection, reflection.getNonIndexSignatures());
+            if (reflection instanceof models_1.SignatureReflection) {
+                this.moveSignatureParamComments(reflection);
             }
         }
-        moveCommentToSignatures(reflection, signatures) {
-            if (!signatures.length) {
+        moveSignatureParamComments(signature, comment = signature.comment) {
+            if (!comment)
                 return;
-            }
-            const comment = reflection.kindOf(models_1.ReflectionKind.ClassOrInterface)
-                ? undefined
-                : reflection.comment;
-            for (const signature of signatures) {
-                const signatureHadOwnComment = !!signature.comment;
-                const childComment = (signature.comment ||= comment?.clone());
-                if (!childComment)
-                    continue;
-                signature.parameters?.forEach((parameter, index) => {
-                    if (parameter.name === "__namedParameters") {
-                        const commentParams = childComment.blockTags.filter((tag) => tag.tag === "@param" && !tag.name?.includes("."));
-                        if (signature.parameters?.length === commentParams.length &&
-                            commentParams[index].name) {
-                            parameter.name = commentParams[index].name;
-                        }
-                    }
-                    const tag = childComment.getIdentifiedTag(parameter.name, "@param");
-                    if (tag) {
-                        parameter.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
-                    }
-                });
-                for (const parameter of signature.typeParameters || []) {
-                    const tag = childComment.getIdentifiedTag(parameter.name, "@typeParam") ||
-                        childComment.getIdentifiedTag(parameter.name, "@template") ||
-                        childComment.getIdentifiedTag(`<${parameter.name}>`, "@param");
-                    if (tag) {
-                        parameter.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+            signature.parameters?.forEach((parameter, index) => {
+                if (parameter.name === "__namedParameters") {
+                    const commentParams = comment.blockTags.filter((tag) => tag.tag === "@param" && !tag.name?.includes("."));
+                    if (signature.parameters?.length === commentParams.length &&
+                        commentParams[index].name) {
+                        parameter.name = commentParams[index].name;
                     }
                 }
-                this.validateParamTags(signature, childComment, signature.parameters || [], signatureHadOwnComment);
-                childComment?.removeTags("@param");
-                childComment?.removeTags("@typeParam");
-                childComment?.removeTags("@template");
-            }
-            // Since this reflection has signatures, we need to remove the comment from the non-primary
-            // declaration location. For functions/methods/constructors, this means removing it from
-            // the wrapping reflection. For type aliases, classes, and interfaces, this means removing
-            // it from the contained signatures... if it's the same as what is on the signature.
-            // This is important so that in type aliases we don't end up with a comment rendered twice.
-            if (reflection.kindOf(models_1.ReflectionKind.SignatureContainer)) {
-                delete reflection.comment;
-            }
-            else {
-                reflection.comment?.removeTags("@param");
-                reflection.comment?.removeTags("@typeParam");
-                reflection.comment?.removeTags("@template");
-                const parentComment = models_1.Comment.combineDisplayParts(reflection.comment?.summary);
-                for (const sig of signatures) {
-                    if (models_1.Comment.combineDisplayParts(sig.comment?.summary) ===
-                        parentComment) {
-                        delete sig.comment;
-                    }
+                const tag = comment.getIdentifiedTag(parameter.name, "@param");
+                if (tag) {
+                    parameter.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+                    parameter.comment.sourcePath = comment.sourcePath;
+                }
+            });
+            for (const parameter of signature.typeParameters || []) {
+                const tag = comment.getIdentifiedTag(parameter.name, "@typeParam") ||
+                    comment.getIdentifiedTag(parameter.name, "@template") ||
+                    comment.getIdentifiedTag(`<${parameter.name}>`, "@param");
+                if (tag) {
+                    parameter.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+                    parameter.comment.sourcePath = comment.sourcePath;
                 }
             }
+            this.validateParamTags(signature, comment, signature.parameters || []);
+            comment.removeTags("@param");
+            comment.removeTags("@typeParam");
+            comment.removeTags("@template");
         }
         removeExcludedTags(comment) {
             for (const tag of NEVER_RENDERED) {
@@ -534,13 +522,13 @@ let CommentPlugin = (() => {
             }
             return excludeCategories.some((cat) => categories.has(cat));
         }
-        validateParamTags(signature, comment, params, signatureHadOwnComment) {
+        validateParamTags(signature, comment, params) {
             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);
-            if (signatureHadOwnComment && paramTags.length) {
+            moveNestedParamTags(/* in-out */ paramTags, params, comment.sourcePath);
+            if (paramTags.length) {
                 for (const tag of paramTags) {
-                    this.application.logger.warn(`The signature ${signature.getFriendlyFullName()} has an @param with name "${tag.name}", which was not used.`);
+                    this.application.logger.warn(this.application.i18n.signature_0_has_unused_param_with_name_1(signature.getFriendlyFullName(), tag.name ?? "(missing)"));
                 }
             }
         }
@@ -588,7 +576,7 @@ function inTypeLiteral(refl) {
 }
 // Moves tags like `@param foo.bar docs for bar` into the `bar` property of the `foo` parameter.
 function moveNestedParamTags(
-/* in-out */ paramTags, parameters) {
+/* in-out */ paramTags, parameters, sourcePath) {
     const used = new Set();
     for (const param of parameters) {
         const visitor = {
@@ -600,6 +588,7 @@ function moveNestedParamTags(
                     const child = target.declaration.getChildByName(path);
                     if (child && !child.comment) {
                         child.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(tag.content));
+                        child.comment.sourcePath = sourcePath;
                         used.add(paramTags.indexOf(tag));
                     }
                 }
@@ -631,9 +620,11 @@ function movePropertyTags(comment, container) {
         const child = container.getChildByName(prop.name);
         if (child) {
             child.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(prop.content));
+            child.comment.sourcePath = comment.sourcePath;
             if (child instanceof models_1.DeclarationReflection && child.signatures) {
                 for (const sig of child.signatures) {
                     sig.comment = new models_1.Comment(models_1.Comment.cloneDisplayParts(prop.content));
+                    sig.comment.sourcePath = comment.sourcePath;
                 }
             }
         }

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

@@ -1,4 +1,4 @@
-import { ContainerReflection, DeclarationReflection } from "../../models/reflections/index";
+import { ContainerReflection, type DeclarationReflection, type DocumentReflection } from "../../models/reflections/index";
 import { ReflectionGroup } from "../../models/ReflectionGroup";
 import { ConverterComponent } from "../components";
 /**
@@ -7,7 +7,7 @@ import { ConverterComponent } from "../components";
  * The handler sets the `groups` property of all container reflections.
  */
 export declare class GroupPlugin extends ConverterComponent {
-    sortFunction: (reflections: DeclarationReflection[]) => void;
+    sortFunction: (reflections: Array<DeclarationReflection | DocumentReflection>) => void;
     accessor boosts: Record<string, number>;
     accessor groupOrder: string[];
     accessor sortEntryPoints: boolean;
@@ -30,7 +30,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @privateRemarks
      * If you change this, also update extractCategories in CategoryPlugin accordingly.
      */
-    getGroups(reflection: DeclarationReflection): Set<string>;
+    getGroups(reflection: DeclarationReflection | DocumentReflection): Set<string>;
     /**
      * Create a grouped representation of the given list of reflections.
      *
@@ -39,7 +39,7 @@ export declare class GroupPlugin extends ConverterComponent {
      * @param reflections  The reflections that should be grouped.
      * @returns An array containing all children of the given reflection grouped by their kind.
      */
-    getReflectionGroups(parent: ContainerReflection, reflections: DeclarationReflection[]): ReflectionGroup[];
+    getReflectionGroups(parent: ContainerReflection, reflections: Array<DeclarationReflection | DocumentReflection>): ReflectionGroup[];
     /**
      * Callback used to sort groups by name.
      */