fix: support @this tag

#251

Author: hosseinmd

src/roles.ts

@@ -38,6 +38,7 @@ import {
   SEE,
   SINCE,
   TEMPLATE,
+  THIS,
   THROWS,
   TODO,
   TYPE,
@@ -94,6 +95,7 @@ const TAGS_NAMELESS = [
   REMARKS,
   RETURNS,
   SINCE,
+  THIS,
   THROWS,
   TODO,
   YIELDS,
@@ -148,6 +150,7 @@ const TAGS_TYPE_NEEDED = [
   PARAM,
   PROPERTY,
   RETURNS,
+  THIS,
   THROWS,
   TYPE,
   SATISFIES,
@@ -160,6 +163,7 @@ const TAGS_VERTICALLY_ALIGN_ABLE = [
   PARAM,
   PROPERTY,
   RETURNS,
+  THIS,
   THROWS,
   TYPE,
   SATISFIES,
@@ -174,6 +178,7 @@ const TAGS_GROUP_CONDITION = [
   PROPERTY,
   PARAM,
   RETURNS,
+  THIS,
   YIELDS,
   THROWS,
 ];
@@ -219,6 +224,7 @@ const TAGS_ORDER = {
   [SATISFIES]: 37,
   [PROPERTY]: 38,
   [CALLBACK]: 39,
+  [THIS]: 39.5,
   [PARAM]: 40,
   [YIELDS]: 41,
   [RETURNS]: 42,

src/tags.ts

@@ -39,6 +39,7 @@ const RETURNS = "returns";
 const SEE = "see";
 const SINCE = "since";
 const TEMPLATE = "template";
+const THIS = "this";
 const THROWS = "throws";
 const TODO = "todo";
 const TYPE = "type";
@@ -98,6 +99,7 @@ export {
   SEE,
   SINCE,
   TEMPLATE,
+  THIS,
   THROWS,
   TODO,
   TYPE,

tests/__snapshots__/exampleTag.test.ts.snap

@@ -113,6 +113,84 @@ exports[`example unParseAble 1`] = `
 "
 `;
 
+exports[`example with @this tag preserves indentation 1`] = `
+"/**
+ * @example
+ *   import { createServer } from "node:http";
+ *   import extendedResponse from "extended-response";
+ *
+ *   async function* messages() {
+ *     for (let i = 1; i <= 5; i++) {
+ *       yield \`Message \${i}\\r\\n\`;
+ *       await new Promise((resolve) => setTimeout(resolve, 1000));
+ *     }
+ *   }
+ *
+ *   const server = createServer(async (req, res) => {
+ *     if (
+ *       req.method === "GET" &&
+ *       new URL(req.url || "").pathname === "/stream5"
+ *     ) {
+ *       await extendedResponse.call(res, {
+ *         messages,
+ *       });
+ *     }
+ *   });
+ *
+ *   server.listen(port, () => {
+ *     console.log(\`Server running on http://localhost:\${port}\`);
+ *   });
+ *
+ * @this {ServerResponse} A Node.js HTTP
+ *   {@link https://nodejs.org/api/http.html#class-httpserverresponse|ServerResponse}
+ *   instance.
+ * @param {object} params Extended Response Parameters
+ * @param {AsyncIterable<message>} params.messages Async messages to be sent
+ *   response stream will be closed
+ * @returns {Promise<void>}
+ */
+"
+`;
+
+exports[`example with @this tag preserves indentation 2`] = `
+"/**
+ * @example
+ *   import { createServer } from "node:http";
+ *   import extendedResponse from "extended-response";
+ *
+ *   async function* messages() {
+ *     for (let i = 1; i <= 5; i++) {
+ *       yield \`Message \${i}\\r\\n\`;
+ *       await new Promise((resolve) => setTimeout(resolve, 1000));
+ *     }
+ *   }
+ *
+ *   const server = createServer(async (req, res) => {
+ *     if (
+ *       req.method === "GET" &&
+ *       new URL(req.url || "").pathname === "/stream5"
+ *     ) {
+ *       await extendedResponse.call(res, {
+ *         messages,
+ *       });
+ *     }
+ *   });
+ *
+ *   server.listen(port, () => {
+ *     console.log(\`Server running on http://localhost:\${port}\`);
+ *   });
+ *
+ * @this {ServerResponse} A Node.js HTTP
+ *   {@link https://nodejs.org/api/http.html#class-httpserverresponse|ServerResponse}
+ *   instance.
+ * @param {object} params Extended Response Parameters
+ * @param {AsyncIterable<message>} params.messages Async messages to be sent
+ *   response stream will be closed
+ * @returns {Promise<void>}
+ */
+"
+`;
+
 exports[`examples Json 1`] = `
 "/**
  * @example

tests/exampleTag.test.ts

@@ -176,3 +176,61 @@ test("example unParseAble", async () => {
   expect(result2).toEqual(result);
   expect(await subject(result)).not.toEqual(result);
 });
+
+test("example with @this tag preserves indentation", async () => {
+  const code = `/**
+ * @example
+ *   import { createServer } from "node:http";
+ *   import extendedResponse from "extended-response";
+ *
+ *   async function* messages() {
+ *     for (let i = 1; i <= 5; i++) {
+ *       yield \`Message \${i}\\r\\n\`;
+ *       await new Promise((resolve) => setTimeout(resolve, 1000));
+ *     }
+ *   }
+ *
+ *   const server = createServer(async (req, res) => {
+ *     if (
+ *       req.method === "GET" &&
+ *       new URL(req.url || "").pathname === "/stream5"
+ *     ) {
+ *       await extendedResponse.call(res, {
+ *         messages,
+ *       });
+ *     }
+ *   });
+ *
+ *   server.listen(port, () => {
+ *     console.log(\`Server running on http://localhost:\${port}\`);
+ *   });
+ *
+ * @param {object} params Extended Response Parameters
+ * @param {AsyncIterable<message>} params.messages Async messages to be sent
+ *   response stream will be closed
+ * @returns {Promise<void>}
+ *
+ * @this {ServerResponse}
+ * A Node.js HTTP
+ * {@link https://nodejs.org/api/http.html#class-httpserverresponse|ServerResponse}
+ * instance.
+ */`;
+
+  const result = await subject(code, {
+    jsdocTagsOrder: '{"this":39.9}' as any,
+    jsdocKeepUnParseAbleExampleIndent: true,
+  });
+
+  expect(result).toMatchSnapshot();
+
+  // Format again to ensure it's stable
+  const result2 = await subject(result, {
+    jsdocTagsOrder: '{"this":39.9}' as any,
+    jsdocKeepUnParseAbleExampleIndent: true,
+  });
+
+  // The example should preserve its indentation
+  expect(result2).toMatchSnapshot();
+  expect(result2).toContain("  import { createServer }");
+  expect(result2).toContain("    for (let i = 1; i <= 5; i++)");
+});