Simplify protoplugin's JSDocBlock type

Remove the toString method, and let GeneratedFile.jsDoc() return a Printable. This brings the JSDocBlock printable in line with others.
bufbuild · Mar 13, 2024 · 8cf665b · 8cf665b
1 parent a57887e
commit 8cf665b
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 48 deletions.
diff --git a/packages/protoplugin/src/next/ecmascript/generated-file.ts b/packages/protoplugin/src/next/ecmascript/generated-file.ts
@@ -26,8 +26,7 @@ import {
 import type { ImportSymbol } from "./import-symbol.js";
 import { createImportSymbol } from "./import-symbol.js";
 import { makeImportPathRelative } from "./import-path.js";
-import type { JSDocBlock } from "./jsdoc.js";
-import { createJsDocBlock } from "./jsdoc.js";
+import { createJsDocTextFromDesc, formatJsDocBlock } from "./jsdoc.js";
 import type { ExportStatement, Printable } from "./printable.js";
 import type { RuntimeImports } from "./runtime-imports.js";
 
@@ -86,14 +85,14 @@ export interface GeneratedFile {
    * Create a JSDoc comment block with the given text. Line breaks and white-space
    * stay intact.
    */
-  jsDoc(text: string, indentation?: string): JSDocBlock;
+  jsDoc(text: string, indentation?: string): Printable;
 
   /**
    * Create a JSDoc comment block for the given message, enumeration, or other
    * descriptor. The comment block will contain the original comments from the
    * protobuf source, and annotations such as `@generated from message MyMessage`.
    */
-  jsDoc(desc: Exclude<AnyDesc, DescFile>, indentation?: string): JSDocBlock;
+  jsDoc(desc: Exclude<AnyDesc, DescFile>, indentation?: string): Printable;
 
   // TODO rename to "export"?
   /**
@@ -227,7 +226,14 @@ export function createGeneratedFile(
       };
     },
     jsDoc(textOrDesc, indentation) {
-      return createJsDocBlock(textOrDesc, indentation);
+      return {
+        kind: "es_jsdoc",
+        text:
+          typeof textOrDesc == "string"
+            ? textOrDesc
+            : createJsDocTextFromDesc(textOrDesc),
+        indentation,
+      };
     },
     importDesc(desc, typeOnly = false) {
       return resolveDescImport(desc, typeOnly);
@@ -410,7 +416,7 @@ function printableToEl(opt: PrintableToElOpt, printables: Printable[]): void {
               break;
             case "es_jsdoc":
               // TODO
-              el.push(p.toString());
+              el.push(formatJsDocBlock(p.text, p.indentation));
               break;
             case "es_string":
               el.push(escapeString(p.value));

diff --git a/packages/protoplugin/src/next/ecmascript/jsdoc.ts b/packages/protoplugin/src/next/ecmascript/jsdoc.ts
@@ -14,49 +14,24 @@
 
 import type { AnyDesc, DescFile } from "@bufbuild/protobuf";
 
-export type JSDocBlock = {
-  readonly kind: "es_jsdoc";
-  /**
-   * @deprecated In a future release, we will make this property optional.
-   */
-  text: string;
-  indentation?: string;
-  /**
-   * @deprecated In a future release, we will remove this method.
-   */
-  toString(): string;
-};
-
-// TODO simplify type JSDocBlock to bring it in line with others in opaque-printables.ts
-export function createJsDocBlock(
-  textOrDesc: string | Exclude<AnyDesc, DescFile>,
-  indentation?: string,
-): JSDocBlock {
-  const text =
-    typeof textOrDesc == "string" ? textOrDesc : createTextForDesc(textOrDesc);
-  return {
-    kind: "es_jsdoc",
-    text,
-    indentation,
-    toString(): string {
-      if (text.trim().length == 0) {
-        return "";
-      }
-      let lines = text.split("\n");
-      if (lines.length === 0) {
-        return "";
-      }
-      lines = lines.map((l) => l.split("*/").join("*\\/"));
-      lines = lines.map((l) => (l.length > 0 ? " " + l : l));
-      const i = indentation ?? "";
-      return [`${i}/**\n`, ...lines.map((l) => `${i} *${l}\n`), `${i} */`].join(
-        "",
-      );
-    },
-  };
+export function formatJsDocBlock(
+  text: string,
+  indentation: string | undefined,
+): string {
+  if (text.trim().length == 0) {
+    return "";
+  }
+  let lines = text.split("\n");
+  if (lines.length === 0) {
+    return "";
+  }
+  lines = lines.map((l) => l.split("*/").join("*\\/"));
+  lines = lines.map((l) => (l.length > 0 ? " " + l : l));
+  const i = indentation ?? "";
+  return [`${i}/**\n`, ...lines.map((l) => `${i} *${l}\n`), `${i} */`].join("");
 }
 
-function createTextForDesc(desc: Exclude<AnyDesc, DescFile>) {
+export function createJsDocTextFromDesc(desc: Exclude<AnyDesc, DescFile>) {
   const comments = desc.getComments();
   let text = "";
   if (comments.leading !== undefined) {

diff --git a/packages/protoplugin/src/next/ecmascript/printable.ts b/packages/protoplugin/src/next/ecmascript/printable.ts
@@ -22,7 +22,6 @@ import type {
   ScalarType,
 } from "@bufbuild/protobuf";
 import type { ImportSymbol } from "./import-symbol.js";
-import type { JSDocBlock } from "./jsdoc.js";
 
 /**
  * All types that can be passed to GeneratedFile.print()
@@ -75,3 +74,9 @@ export type ShapeImport = {
   readonly kind: "es_shape_ref";
   desc: DescMessage | DescEnum;
 };
+
+export type JSDocBlock = {
+  readonly kind: "es_jsdoc";
+  text: string;
+  indentation?: string;
+};