Add warnings for bad @param tags

Gerrit0 · Gerrit0 · commit 5e108b6cd0cb · 2023-12-29T19:55:00.000-07:00
Resolves #2368
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## Features
 
+-   TypeDoc now provides warnings if a signature comment is directly specified on a signature and contains `@param` tags which do not apply, #2368.
 -   Extended reflection preview view for interfaces to include type parameters, #2455.
 -   Added special cases for converting methods which are documented as returning `this` or accepting `this` as a parameter, #2458.
     Note: This will only happen if a method is declared as `method(): this`, it will not happen if the method implicitly returns `this`
diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts
@@ -21,6 +21,7 @@ import {
     removeIfPresent,
     unique,
     partition,
+    removeIf,
 } from "../../utils";
 import { CategoryPlugin } from "./CategoryPlugin";
 
@@ -388,6 +389,7 @@ export class CommentPlugin extends ConverterComponent {
             : reflection.comment;
 
         for (const signature of signatures) {
+            const signatureHadOwnComment = !!signature.comment;
             const childComment = (signature.comment ||= comment?.clone());
             if (!childComment) continue;
 
@@ -405,7 +407,6 @@ export class CommentPlugin extends ConverterComponent {
                     }
                 }
 
-                moveNestedParamTags(childComment, parameter);
                 const tag = childComment.getIdentifiedTag(
                     parameter.name,
                     "@param",
@@ -439,6 +440,13 @@ export class CommentPlugin extends ConverterComponent {
                 }
             }
 
+            this.validateParamTags(
+                signature,
+                childComment,
+                signature.parameters || [],
+                signatureHadOwnComment,
+            );
+
             childComment?.removeTags("@param");
             childComment?.removeTags("@typeParam");
             childComment?.removeTags("@template");
@@ -590,6 +598,33 @@ export class CommentPlugin extends ConverterComponent {
 
         return excludeCategories.some((cat) => categories.has(cat));
     }
+
+    private validateParamTags(
+        signature: SignatureReflection,
+        comment: Comment,
+        params: ParameterReflection[],
+        signatureHadOwnComment: boolean,
+    ) {
+        const paramTags = comment.blockTags.filter(
+            (tag) => tag.tag === "@param",
+        );
+
+        removeIf(paramTags, (tag) =>
+            params.some((param) => param.name === tag.name),
+        );
+
+        moveNestedParamTags(/* in-out */ paramTags, params);
+
+        if (signatureHadOwnComment && 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.`,
+                );
+            }
+        }
+    }
 }
 
 function inTypeLiteral(refl: Reflection | undefined) {
@@ -603,37 +638,51 @@ function inTypeLiteral(refl: Reflection | undefined) {
 }
 
 // Moves tags like `@param foo.bar docs for bar` into the `bar` property of the `foo` parameter.
-function moveNestedParamTags(comment: Comment, parameter: ParameterReflection) {
-    const visitor: Partial<TypeVisitor> = {
-        reflection(target) {
-            const tags = comment.blockTags.filter(
-                (t) =>
-                    t.tag === "@param" &&
-                    t.name?.startsWith(`${parameter.name}.`),
-            );
+function moveNestedParamTags(
+    /* in-out */ paramTags: CommentTag[],
+    parameters: ParameterReflection[],
+) {
+    const used = new Set<number>();
+
+    for (const param of parameters) {
+        const visitor: Partial<TypeVisitor> = {
+            reflection(target) {
+                const tags = paramTags.filter(
+                    (t) => t.name?.startsWith(`${param.name}.`),
+                );
 
-            for (const tag of tags) {
-                const path = tag.name!.split(".");
-                path.shift();
-                const child = target.declaration.getChildByName(path);
+                for (const tag of tags) {
+                    const path = tag.name!.split(".");
+                    path.shift();
+                    const child = target.declaration.getChildByName(path);
 
-                if (child && !child.comment) {
-                    child.comment = new Comment(
-                        Comment.cloneDisplayParts(tag.content),
-                    );
+                    if (child && !child.comment) {
+                        child.comment = new Comment(
+                            Comment.cloneDisplayParts(tag.content),
+                        );
+                        used.add(paramTags.indexOf(tag));
+                    }
                 }
-            }
-        },
-        // #1876, also do this for unions/intersections.
-        union(u) {
-            u.types.forEach((t) => t.visit(visitor));
-        },
-        intersection(i) {
-            i.types.forEach((t) => t.visit(visitor));
-        },
-    };
-
-    parameter.type?.visit(visitor);
+            },
+            // #1876, also do this for unions/intersections.
+            union(u) {
+                u.types.forEach((t) => t.visit(visitor));
+            },
+            intersection(i) {
+                i.types.forEach((t) => t.visit(visitor));
+            },
+        };
+
+        param.type?.visit(visitor);
+    }
+
+    const toRemove = Array.from(used)
+        .sort((a, b) => a - b)
+        .reverse();
+
+    for (const index of toRemove) {
+        paramTags.splice(index, 1);
+    }
 }
 
 function movePropertyTags(comment: Comment, container: Reflection) {
diff --git a/src/test/behavior.c2.test.ts b/src/test/behavior.c2.test.ts
@@ -1046,4 +1046,43 @@ describe("Behavior Tests", () => {
             "this",
         );
     });
+
+    it("Handles renaming of destructured parameters via @param tag name inference", () => {
+        const project = convert("destructuredParamRenames");
+
+        const params = (name: string) =>
+            querySig(project, name).parameters?.map((p) => p.name);
+
+        equal(params("functionWithADestructuredParameter"), [
+            "destructuredParam",
+        ]);
+
+        equal(params("functionWithADestructuredParameterAndExtraParameters"), [
+            "__namedParameters",
+            "extraParameter",
+        ]);
+
+        equal(
+            params(
+                "functionWithADestructuredParameterAndAnExtraParamDirective",
+            ),
+            ["__namedParameters"],
+        );
+
+        const logs = [
+            'warn: The signature functionWithADestructuredParameterAndExtraParameters has an @param with name "destructuredParam", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndExtraParameters has an @param with name "destructuredParam.paramZ", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndExtraParameters has an @param with name "destructuredParam.paramG", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndExtraParameters has an @param with name "destructuredParam.paramA", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndAnExtraParamDirective has an @param with name "fakeParameter", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndAnExtraParamDirective has an @param with name "destructuredParam", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndAnExtraParamDirective has an @param with name "destructuredParam.paramZ", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndAnExtraParamDirective has an @param with name "destructuredParam.paramG", which was not used.',
+            'warn: The signature functionWithADestructuredParameterAndAnExtraParamDirective has an @param with name "destructuredParam.paramA", which was not used.',
+        ];
+        for (const log of logs) {
+            logger.expectMessage(log);
+        }
+        logger.expectNoOtherMessages();
+    });
 });
diff --git a/src/test/converter/function/function.ts b/src/test/converter/function/function.ts
@@ -79,102 +79,6 @@ export function functionWithRest(...rest: string[]): string {
     return rest.join(", ");
 }
 
-/**
- * This is a function with a destructured parameter.
- *
- * @param destructuredParam - This is the parameter that is destructured.
- * @param destructuredParam.paramZ - This is a string parameter.
- * @param destructuredParam.paramG - This is a parameter flagged with any.
- *     This sentence is placed in the next line.
- *
- * @param destructuredParam.paramA
- *   This is a **parameter** pointing to an interface.
- *
- *   ```
- *   const value:BaseClass = new BaseClass('test');
- *   functionWithArguments('arg', 0, value);
- *   ```
- *
- * @returns This is the return value of the function.
- */
-export function functionWithADestructuredParameter({
-    paramZ,
-    paramG,
-    paramA,
-}: {
-    paramZ: string;
-    paramG: any;
-    paramA: Object;
-}): number {
-    return 0;
-}
-
-/**
- * This is a function with a destructured parameter and additional undocumented parameters.
- * The `@param` directives are ignored because we cannot be certain which parameter they refer to.
- *
- * @param destructuredParam - This is the parameter that is destructured.
- * @param destructuredParam.paramZ - This is a string parameter.
- * @param destructuredParam.paramG - This is a parameter flagged with any.
- *     This sentence is placed in the next line.
- *
- * @param destructuredParam.paramA
- *   This is a **parameter** pointing to an interface.
- *
- *   ```
- *   const value:BaseClass = new BaseClass('test');
- *   functionWithArguments('arg', 0, value);
- *   ```
- *
- * @returns This is the return value of the function.
- */
-export function functionWithADestructuredParameterAndExtraParameters(
-    {
-        paramZ,
-        paramG,
-        paramA,
-    }: {
-        paramZ: string;
-        paramG: any;
-        paramA: Object;
-    },
-    extraParameter: string,
-): number {
-    return 0;
-}
-
-/**
- * This is a function with a destructured parameter and an extra `@param` directive with no corresponding parameter.
- * The `@param` directives are ignored because we cannot be certain which corresponds to the real parameter.
- *
- * @param fakeParameter - This directive does not have a corresponding parameter.
- * @param destructuredParam - This is the parameter that is destructured.
- * @param destructuredParam.paramZ - This is a string parameter.
- * @param destructuredParam.paramG - This is a parameter flagged with any.
- *     This sentence is placed in the next line.
- *
- * @param destructuredParam.paramA
- *   This is a **parameter** pointing to an interface.
- *
- *   ```
- *   const value:BaseClass = new BaseClass('test');
- *   functionWithArguments('arg', 0, value);
- *   ```
- *
- * @returns This is the return value of the function.
- */
-export function functionWithADestructuredParameterAndAnExtraParamDirective({
-    paramZ,
-    paramG,
-    paramA,
-}: {
-    paramZ: string;
-    paramG: any;
-    paramA: Object;
-}): number {
-    return 0;
-}
-
 /**
  * This is the first signature of a function with multiple signatures.
  *
diff --git a/src/test/converter/function/specs.json b/src/test/converter/function/specs.json
diff --git a/src/test/converter2/behavior/destructuredParamRenames.ts b/src/test/converter2/behavior/destructuredParamRenames.ts
