Do not append trailing spaces to JSDoc tags (#1231)

* Fix pnpm format script

* Do not append trailing spaces to JSDoc tags

* Further remove trailing spaces

* Update examples

Author: tkrotoff

.changeset/funny-lies-tease.md

@@ -0,0 +1,5 @@
+---
+"openapi-typescript": patch
+---
+
+Do not append trailing spaces to JSDoc tags

packages/openapi-typescript/examples/digital-ocean-api.ts

@@ -41,10 +41,10 @@
     "build": "del dist && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "download:schemas": "vite-node ./scripts/download-schemas.ts",
-    "format": "pnpm run prettier -w .",
+    "format": "prettier --write 'src/**/*'",
     "lint": "run-p -s lint:*",
-    "lint:js": "eslint \"src/**/*.{js,ts}\"",
-    "lint:prettier": "prettier --check \"src/**/*\"",
+    "lint:js": "eslint 'src/**/*.{js,ts}'",
+    "lint:prettier": "prettier --check 'src/**/*'",
     "prepare": "pnpm run build",
     "test": "run-p -s test:*",
     "test:js": "vitest run",

packages/openapi-typescript/examples/github-api-next.ts

@@ -55,13 +55,13 @@ export function getSchemaObjectComment(v: CommentObject, indentLv?: number): str
   const output: string[] = [];
 
   // * Not JSDOC tags: [title, format]
-  if (v.title) output.push(`${v.title} `);
-  if (v.summary) output.push(`${v.summary} `);
-  if (v.format) output.push(`Format: ${v.format} `);
+  if (v.title) output.push(v.title);
+  if (v.summary) output.push(v.summary);
+  if (v.format) output.push(`Format: ${v.format}`);
 
   // * JSDOC tags without value
   // 'Deprecated' without value
-  if (v.deprecated) output.push(`@deprecated `);
+  if (v.deprecated) output.push("@deprecated");
 
   // * JSDOC tags with value
   const supportedJsDocTags: (keyof CommentObject)[] = ["description", "default", "example"];
@@ -74,11 +74,11 @@ export function getSchemaObjectComment(v: CommentObject, indentLv?: number): str
       continue;
     }
     const serialized = typeof v[field] === "object" ? JSON.stringify(v[field], null, 2) : v[field];
-    output.push(`@${field} ${serialized} `);
+    output.push(`@${field} ${serialized}`);
   }
 
   // * JSDOC 'Constant' without value
-  if ("const" in v) output.push(`@constant `);
+  if ("const" in v) output.push("@constant");
 
   // * JSDOC 'Enum' with type
   if (v.enum) {
@@ -99,8 +99,14 @@ export function comment(text: string, indentLv?: number): string {
   if (!commentText.includes("\n")) return `/** ${commentText} */`;
 
   // if multi-line comment
-  const ln = indent(" * ", indentLv ?? 0);
-  return ["/**", `${ln}${commentText.replace(LB_RE, `\n${ln}`)}`, indent(" */", indentLv ?? 0)].join("\n");
+  const star = indent(" *", indentLv ?? 0);
+
+  const body = commentText.split(LB_RE).map((ln) => {
+    ln = ln.trimEnd();
+    return ln.length > 0 ? `${star} ${ln}` : star;
+  });
+
+  return ["/**", body.join("\n"), indent(" */", indentLv ?? 0)].join("\n");
 }
 
 /** handle any valid $ref */

packages/openapi-typescript/examples/github-api.ts

@@ -1,5 +1,5 @@
 import { bench } from "vitest";
-import { escObjKey, parseRef, tsIntersectionOf, tsUnionOf } from "../src/utils.js";
+import { comment, escObjKey, getSchemaObjectComment, parseRef, tsIntersectionOf, tsUnionOf } from "../src/utils.js";
 
 describe("utils", () => {
   describe("tsUnionOf", () => {
@@ -112,4 +112,60 @@ describe("utils", () => {
       expect(escObjKey("_ref_")).toStrictEqual("_ref_");
     });
   });
+
+  describe("comment", () => {
+    it("basic", () => {
+      expect(comment("A comment")).toStrictEqual("/** A comment */");
+      expect(comment("A multi-line \n\n comment")).toStrictEqual(
+        // prettier-ignore
+        "/**\n" +
+        " * A multi-line\n" +
+        " *\n" +
+        " *  comment\n"+
+        " */"
+      );
+    });
+  });
+
+  describe("getSchemaObjectComment", () => {
+    it("object with 1 property", () => {
+      expect(
+        getSchemaObjectComment({
+          title: "A title",
+        })
+      ).toStrictEqual("/** A title */");
+    });
+
+    it("object with 2 properties", () => {
+      expect(
+        getSchemaObjectComment({
+          title: "A title",
+          description: "A description",
+        })
+      ).toStrictEqual(
+        // prettier-ignore
+        "/**\n" +
+        " * A title\n" +
+        " * @description A description\n"+
+        " */"
+      );
+    });
+
+    it("object with a multi-line property", () => {
+      expect(
+        getSchemaObjectComment({
+          title: "A title",
+          description: "A multi-line \n\n description",
+        })
+      ).toStrictEqual(
+        // prettier-ignore
+        "/**\n" +
+        " * A title\n" +
+        " * @description A multi-line\n" +
+        " *\n" +
+        " *  description\n" +
+        " */"
+      );
+    });
+  });
 });