Handle @this tag, improved destructured parameters

Resolves #3026

Author: Gerrit0

CHANGELOG.md

@@ -10,11 +10,13 @@ title: Changelog
   be copied to the output documentation, #3020.
   API: Introduced `typeAnnotation` on `CommentTag`
 - Added `excludePrivateClassFields` option to hide `#private` members while allowing `private` members, #3017.
+- Added support for TypeScript's `@this` tag for JS files which describe `this` parameters, #3026.
 
 ## Bug Fixes
 
 - Fixed conversion of auto-accessor types on properties with the `accessor` keyword, #3019.
 - Improved handling of HTML tags within headers for anchor generation, #3023.
+- Improved support for detecting destructured parameters and renaming them to the name used in the doc comment, #3026.
 
 ## v0.28.13 (2025-09-14)
 

package.json

@@ -73,9 +73,9 @@
         "test": "mocha --config .config/mocha.fast.json",
         "test:cov": "c8 -r lcov mocha --config .config/mocha.fast.json",
         "doc:c": "node bin/typedoc --tsconfig src/test/converter/tsconfig.json",
-        "doc:cd": "node --inspect-brk bin/typedoc --tsconfig src/test/converter/tsconfig.json",
+        "doc:cd": "node --inspect-brk dist/lib/cli.js --tsconfig src/test/converter/tsconfig.json",
         "doc:c2": "node bin/typedoc --options src/test/converter2 --tsconfig src/test/converter2/tsconfig.json",
-        "doc:c2d": "node --inspect-brk bin/typedoc --options src/test/converter2 --tsconfig src/test/converter2/tsconfig.json",
+        "doc:c2d": "node --inspect-brk dist/lib/cli.js --options src/test/converter2 --tsconfig src/test/converter2/tsconfig.json",
         "example": "cd example && node ../bin/typedoc",
         "test:full": "c8 -r lcov -r text-summary mocha --config .config/mocha.full.json",
         "rebuild_specs": "node scripts/rebuild_specs.js",

site/tags.md

@@ -122,7 +122,7 @@ examples for how to use the export ([`@example`](./tags/example.md)).
 - [`@license`](./tags/license.md)
 - [`@mergeModuleWith`](./tags/mergeModuleWith.md)
 - [`@module`](./tags/module.md)
-- [`@param`](./tags/param.md)
+- [`@param`, `@this`](./tags/param.md)
 - [`@preventExpand`](./tags/expand.md#preventexpand)
 - [`@preventInline`](./tags/inline.md#preventinline)
 - [`@privateRemarks`](./tags/privateRemarks.md)

site/tags/param.md

@@ -2,7 +2,7 @@
 title: "@param"
 ---
 
-# @param
+# @param and @this
 
 **Tag Kind:** [Block](../tags.md#block-tags) <br>
 **TSDoc Reference:** [@param](https://tsdoc.org/pages/tags/param/)
@@ -54,6 +54,21 @@ export function configure({ value }: { value: string }) {}
 export function configure(options: { value: string }) {}
 ```
 
+## `this` Parameters
+
+Functions which use `this` in JavaScript files may use TypeScript's `@this` tag to define the type of their `this`
+parameter. TypeDoc will check for `@this` tags and use their content in the description of the `this` parameter.
+
+```js
+/**
+ * @this {Request} parameter description for `this`
+ * @param {Response} response parameter description for `response`
+ */
+export function hello(response) {
+    response.write(`Hello ${this.query.name || "world!"}`);
+}
+```
+
 ## TSDoc Compatibility
 
 The TSDoc standard requires that the `@param` tag _not_ include types and that

src/lib/converter/factories/signature.ts

@@ -163,7 +163,7 @@ export function createConstructSignatureWithType(
         }
     }
 
-    const parameterSymbols: Array<ts.Symbol & { type?: ts.Type }> = signature.thisParameter
+    const parameterSymbols = signature.thisParameter
         ? [signature.thisParameter, ...signature.parameters]
         : [...signature.parameters];
 
@@ -207,7 +207,7 @@ export function createConstructSignatureWithType(
 function convertParameters(
     context: Context,
     sigRef: SignatureReflection,
-    parameters: readonly (ts.Symbol & { type?: ts.Type })[],
+    parameters: readonly ts.Symbol[],
     parameterNodes:
         | readonly ts.ParameterDeclaration[]
         | readonly ts.JSDocParameterTag[]
@@ -226,7 +226,7 @@ function convertParameters(
                 ts.isJSDocParameterTag(declaration),
         );
         const paramRefl = new ParameterReflection(
-            /__\d+/.test(param.name) ? "__namedParameters" : param.name,
+            /^__\d+$/.test(param.name) ? "__namedParameters" : param.name,
             ReflectionKind.Parameter,
             sigRef,
         );
@@ -256,7 +256,7 @@ function convertParameters(
                 typeNode = declaration.typeExpression?.type;
             }
         } else {
-            type = param.type;
+            type = context.checker.getTypeOfSymbol(param);
         }
 
         if (
@@ -295,8 +295,9 @@ function convertParameters(
         paramRefl.setFlag(ReflectionFlag.Optional, isOptional);
 
         // If we have no declaration, then this is an implicitly defined parameter in JS land
-        // because the method body uses `arguments`... which is always a rest argument
-        let isRest = true;
+        // because the method body uses `arguments`... which is always a rest argument,
+        // unless it is a this parameter defined with @this in JSDoc.
+        let isRest = param.name !== "this";
         if (declaration) {
             isRest = ts.isParameter(declaration)
                 ? !!declaration.dotDotDotToken

src/lib/converter/plugins/CommentPlugin.ts

@@ -37,9 +37,9 @@ import { CategoryPlugin } from "./CategoryPlugin.js";
  * (for JS users) will be consumed by TypeScript and need not be preserved
  * in the comment.
  *
- * Note that param/arg/argument/return/returns are not present.
+ * Note that param/arg/argument/return/returns/this are not present.
  * These tags will have their type information stripped when parsing, but still
- * provide useful information for documentation.
+ * may provide useful information for documentation.
  */
 const NEVER_RENDERED = [
     "@augments",
@@ -48,7 +48,6 @@ const NEVER_RENDERED = [
     "@constructor",
     "@enum",
     "@extends",
-    "@this",
     "@type",
     "@typedef",
     "@jsx",
@@ -479,26 +478,29 @@ export class CommentPlugin extends ConverterComponent {
     ) {
         if (!comment) return;
 
-        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!;
-                }
+        const unusedCommentParams = comment.blockTags.filter(
+            (tag) =>
+                tag.tag === "@param" && tag.name && !tag.name.includes(".") &&
+                !signature.parameters?.some(p => p.name === tag.name),
+        );
+
+        signature.parameters?.forEach((parameter) => {
+            if (parameter.name === "__namedParameters" && unusedCommentParams.length) {
+                parameter.name = unusedCommentParams[0].name!;
+                unusedCommentParams.splice(0, 1);
             }
 
             const tag = comment.getIdentifiedTag(parameter.name, "@param");
 
             if (tag) {
-                parameter.comment = new Comment(
-                    Comment.cloneDisplayParts(tag.content),
-                );
+                parameter.comment = new Comment(Comment.cloneDisplayParts(tag.content));
                 parameter.comment.sourcePath = comment.sourcePath;
+            } else if (parameter.name === "this") {
+                const thisTag = comment.getTag("@this");
+                if (thisTag) {
+                    parameter.comment = new Comment(Comment.cloneDisplayParts(thisTag.content));
+                    parameter.comment.sourcePath = comment.sourcePath;
+                }
             }
         });
 
@@ -516,6 +518,7 @@ export class CommentPlugin extends ConverterComponent {
 
         this.validateParamTags(signature, comment, signature.parameters || []);
 
+        comment.removeTags("@this");
         comment.removeTags("@param");
         comment.removeTags("@typeParam");
         comment.removeTags("@template");

src/lib/utils/options/tsdoc-defaults.ts

@@ -39,6 +39,7 @@ export const blockTags = [
     "@since",
     "@sortStrategy",
     "@template", // Alias for @typeParam
+    "@this",
     "@type",
     "@typedef",
     "@summary",

src/test/TestLogger.ts

@@ -41,10 +41,8 @@ export class TestLogger extends Logger {
         }
     }
 
-    expectNoOtherMessages({ ignoreDebug } = { ignoreDebug: true }) {
-        const messages = ignoreDebug
-            ? this.messages.filter((msg) => !msg.startsWith("debug"))
-            : this.messages;
+    expectNoOtherMessages() {
+        const messages = this.messages.filter((msg) => !msg.startsWith("debug"));
 
         ok(
             messages.length === 0,

src/test/behavior.c2.test.ts

@@ -1118,36 +1118,17 @@ describe("Behavior Tests", () => {
 
         const params = (name: string) => querySig(project, name).parameters?.map((p) => p.name);
 
-        equal(params("functionWithADestructuredParameter"), [
-            "destructuredParam",
-        ]);
+        equal(params("singleParam"), ["params"]);
 
-        equal(params("functionWithADestructuredParameterAndExtraParameters"), [
-            "__namedParameters",
-            "extraParameter",
-        ]);
+        equal(params("extraParam"), ["params", "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);
-        }
+        equal(params("extraParamComment"), ["params"]);
+
+        equal(params("multiParam"), ["params", "params2", "__namedParameters"]);
+
+        logger.expectMessage(
+            'warn: The signature extraParamComment has an @param with name "fakeParameter", which was not used',
+        );
         logger.expectNoOtherMessages();
     });
 

src/test/converter2/behavior/destructuredParamRenames.ts

@@ -1,95 +1,34 @@
 /**
- * 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.
+ * @param params - desc
+ * @param params.a - paramZ desc
  */
-export function functionWithADestructuredParameter({
-    paramZ,
-    paramG,
-    paramA,
-}: {
-    paramZ: string;
-    paramG: any;
-    paramA: Object;
-}): number {
+export function singleParam({ a }: { a: string }) {
     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.
+ * @param params - desc
  */
-export function functionWithADestructuredParameterAndExtraParameters(
-    {
-        paramZ,
-        paramG,
-        paramA,
-    }: {
-        paramZ: string;
-        paramG: any;
-        paramA: Object;
-    },
-    extraParameter: string,
-): number {
+export function extraParam({ a }: { a: string }, extraParameter: string) {
     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.
+ * @param params param
+ * @param fakeParameter param2
  */
-export function functionWithADestructuredParameterAndAnExtraParamDirective({
-    paramZ,
-    paramG,
-    paramA,
-}: {
-    paramZ: string;
-    paramG: any;
-    paramA: Object;
-}): number {
+export function extraParamComment({ a }: { a: string }) {
+    return 0;
+}
+
+/**
+ * @param params params
+ * @param params2 params2
+ */
+export function multiParam(
+    { a }: { a: string },
+    { b }: { b: number },
+    { c }: { c: boolean },
+) {
     return 0;
 }