fix: escape jsdoc in comments

whisklabs · Sep 8, 2021 · 55eb047 · 55eb047
1 parent c7ce4c3
commit 55eb047
Show file tree

Hide file tree

Showing 7 changed files with 59 additions and 37 deletions.
diff --git a/proto/whisk/api/user/v2/user.proto b/proto/whisk/api/user/v2/user.proto
@@ -191,6 +191,13 @@ enum EthicalPreference {
   ETHICAL_PREFERENCE_LOW_WASTE_PRODUCTS = 6;
 }
 
+//   optional string corge = 5;
+//   /* Block comment attached
+//    * to corge.  Leading asterisks
+//    * will be removed. */
+//   /* Block comment attached to
+//    * grault. */
+//   optional int32 grault = 6;
 message Recommendations { int32 daily_calories = 1; }
 
 message TestItem {
@@ -261,6 +268,8 @@ message SearchRecipesResponse {
     map<string, TestItem> map_external = 5;
   }
 
+  // If true, when this message is used as an optional field, do not wrap it in an `Option`.
+  // This is equivalent of setting `(field).no_box` to true on each field with the message type.
   message Height {
     enum Unit2 {
       UNIT_INVALID = 0;

diff --git a/src/generator/enum.ts b/src/generator/enum.ts
@@ -2,7 +2,7 @@ import { isNumber, isText } from '@whisklabs/typeguards';
 
 import { Parser } from '../parser';
 import { MakeOuts } from './generator';
-import { checkSame, safeString } from './utils';
+import { checkSame, safeString, toComment } from './utils';
 
 export function enums(pack: string, out: MakeOuts, items: Parser.Enum[]) {
   for (const msg of items) {
@@ -17,7 +17,7 @@ function enu(pack: string, out: MakeOuts, item: Parser.Enum) {
   const cName = checkSame(out, 'name');
 
   if (isText(item.comment)) {
-    out.dts.push(`/** ${item.comment.trim()} */`);
+    out.dts.push(toComment(item.comment));
   }
 
   out.js.push(`export const ${eName} = {`);
@@ -31,7 +31,7 @@ function enu(pack: string, out: MakeOuts, item: Parser.Enum) {
       cName(field, `${pack}.${field}`);
       out.js.push(`  ${field}: ${val},`);
       if (isText(comment)) {
-        out.dts.push(`/** ${comment} */`);
+        out.dts.push(toComment(comment));
       }
       out.dts.push(`  readonly ${field}: ${val},`);
     }

diff --git a/src/generator/message.ts b/src/generator/message.ts
@@ -5,7 +5,7 @@ import { GOOGLE_WRAPPERS, OPTION_MESSAGE_REQUIRED } from './constants';
 import { enums } from './enum';
 import { getField, getStruct, isRequiredField } from './field';
 import { List, MakeOut, MakeOuts } from './generator';
-import { camelCase, checkSame, errorColor, safeString } from './utils';
+import { camelCase, checkSame, errorColor, safeString, toComment } from './utils';
 
 export function messages(
   pack: string,
@@ -133,7 +133,7 @@ function message(
   }
 
   if (isText(item.comment)) {
-    out.dts.push(`/** ${item.comment.trim()} */`);
+    out.dts.push(toComment(item.comment));
   }
   out.dts.push(`export const ${baseName}: Field<${baseName}>;`);
   out.js.push(`export function ${baseName} () { return [`);
@@ -155,6 +155,6 @@ function getComment(field: Parser.Field, out: MakeOuts) {
   }
 
   if (isText(comment)) {
-    out.dts.push(`  /** ${comment.trim()} */`);
+    out.dts.push(toComment(comment));
   }
 }
diff --git a/src/generator/service.ts b/src/generator/service.ts
@@ -3,7 +3,7 @@ import { isText } from '@whisklabs/typeguards';
 import { Parser } from '../parser';
 import { pathField } from './field';
 import { MakeOuts } from './generator';
-import { safeString } from './utils';
+import { safeString, toComment } from './utils';
 
 export function services(pack: string, out: MakeOuts, items: Parser.Service[] = []) {
   for (const msg of items) {
@@ -25,7 +25,7 @@ export function method(pack: string, out: MakeOuts, item: Parser.Method, serv: P
   out.fields.push([input, sName], [output, sName]);
 
   if (isText(item.comment)) {
-    out.dts.push(`/** ${item.comment.trim()} */`);
+    out.dts.push(toComment(item.comment));
   }
   out.dts.push(`export type ${sName} = Service<Field<${input}>, Field<${output}>>;`);
   out.dts.push(`export const ${sName}: ${sName};`);

diff --git a/src/generator/utils.ts b/src/generator/utils.ts
@@ -46,3 +46,5 @@ export async function walk<T>({ filename, each, result }: WalkInit<T>): Promise<
   }
   return result;
 }
+
+export const toComment = (str: string) => `/** ${str.replace(/\*\//g, '*∕').trim()} */`;
diff --git a/tests/proto/debug/whisk/api/user/v2/user.json b/tests/proto/debug/whisk/api/user/v2/user.json
@@ -1021,7 +1021,8 @@
       ],
       "extends": [],
       "extensions": [],
-      "reserved": []
+      "reserved": [],
+      "comment": "   optional string corge = 5;\n   /* Block comment attached\n    * to corge.  Leading asterisks\n    * will be removed. */\n   /* Block comment attached to\n    * grault. */\n   optional int32 grault = 6;"
     },
     {
       "name": "TestItem",
@@ -1485,7 +1486,8 @@
           "fields": [],
           "extends": [],
           "extensions": [],
-          "reserved": []
+          "reserved": [],
+          "comment": " If true, when this message is used as an optional field, do not wrap it in an `Option`.\n This is equivalent of setting `(field).no_box` to true on each field with the message type."
         }
       ],
       "fields": [

diff --git a/tests/proto/index.d.ts b/tests/proto/index.d.ts
@@ -24,11 +24,11 @@ export const google_protobuf_Syntax: {
 export type google_protobuf_Syntax = Values<typeof google_protobuf_Syntax>;
 /** Describes goals */
 export const whisk_api_user_v2_HealthGoal: {
-/**  Loss */
+/** Loss */
   readonly HEALTH_GOAL_WEIGHT_LOSS: 1,
-/**  Gain */
+/** Gain */
   readonly HEALTH_GOAL_WEIGHT_GAIN: 2,
-/** * Sleep  */
+/** * Sleep */
   readonly HEALTH_GOAL_BETTER_SLEEP: 3,
   readonly HEALTH_GOAL_INCREASE_ENERGY: 4,
 };
@@ -271,7 +271,7 @@ export type google_protobuf_FileOptions = {
   javaPackage?: string;
   javaOuterClassname?: string;
   javaMultipleFiles?: boolean;
-  /** @deprecated */
+/** @deprecated */
   javaGenerateEqualsAndHash?: boolean;
   javaStringCheckUtf8?: boolean;
   optimizeFor?: google_protobuf_FileOptions_OptimizeMode;
@@ -546,14 +546,14 @@ export const whisk_api_shared_v1_Test_Enum: {
 };
 export type whisk_api_shared_v1_Test_Enum = Values<typeof whisk_api_shared_v1_Test_Enum>;
 export type whisk_api_shared_v1_Test = {
-  /** * Multi
+/** * Multi
   line /** test *\/ */
   string: string;
-  /** Up lime */
+/** Up lime */
   uint32: number;
-  /** Side line */
+/** Side line */
   inner?: whisk_api_shared_v1_Test_Inner;
-  /** *
+/** *
    * Represents a book.
    * @constructor
    * @param {string} title - The title of the book.
@@ -587,9 +587,9 @@ export type whisk_api_shared_v1_Date = {
 };
 export const whisk_api_shared_v1_Date: Field<whisk_api_shared_v1_Date>;
 export type whisk_api_shared_v1_Time = {
-  /** required */
+/** required */
   time: number;
-  /** optional */
+/** optional */
   nano?: number;
 };
 export const whisk_api_shared_v1_Time: Field<whisk_api_shared_v1_Time>;
@@ -647,32 +647,32 @@ export type whisk_api_shared_v1_Wrapper = {
 };
 export const whisk_api_shared_v1_Wrapper: Field<whisk_api_shared_v1_Wrapper>;
 export type whisk_api_user_v2_Test = {
-  /** required */
+/** required */
   id: string;
-  /** optional */
+/** optional */
   text?: string;
-  /** required */
+/** required */
   currentWeek: whisk_api_user_v2_Week;
-  /** optional */
+/** optional */
   nextWeek?: whisk_api_user_v2_Week;
-  /** required */
+/** required */
   time: whisk_api_shared_v1_Time;
-  /** optional */
+/** optional */
   timeAfter?: whisk_api_shared_v1_Time;
-  /** Optional string */
+/** Optional string */
   description: string;
-  /** Force override (backward binary compatibility only) */
+/** Force override (backward binary compatibility only) */
   item?: string;
   test: string;
-  /** required */
+/** required */
   array: boolean[];
   array_2?: boolean[];
-  /** Map - can't work with optional!
+/** Map - can't work with optional!
  required */
   mapSearch: Record<string, boolean>;
   mapSearch_2?: Record<string, boolean>;
   deviceDescription?:
-  /** required */
+/** required */
     | { oneof: 'type'; value: whisk_api_user_v2_Week; }
     | { oneof: 'custom'; value?: whisk_api_user_v2_Week; };
 };
@@ -716,7 +716,7 @@ export type whisk_api_user_v2_PersonalDetails = {
   zipcode: string;
   language: string;
   activityLevel?: whisk_api_user_v2_ActivityLevel;
-  /** @deprecated */
+/** @deprecated */
   age: number;
   height?: whisk_api_user_v2_Height;
   weight?: whisk_api_user_v2_Weight;
@@ -830,18 +830,25 @@ export const whisk_api_user_v2_Ingredient: Field<whisk_api_user_v2_Ingredient>;
 export type whisk_api_user_v2_Recommendations = {
   dailyCalories: number;
 };
+/** optional string corge = 5;
+   /* Block comment attached
+    * to corge.  Leading asterisks
+    * will be removed. *∕
+   /* Block comment attached to
+    * grault. *∕
+   optional int32 grault = 6; */
 export const whisk_api_user_v2_Recommendations: Field<whisk_api_user_v2_Recommendations>;
 export type whisk_api_user_v2_TestItem = {
-  /** Required */
+/** Required */
   id: string;
   name: string;
   surname?: string;
-  /** Optional */
+/** Optional */
   description?: string;
   test: string;
   array: string[];
   story?: string;
-  /** External message */
+/** External message */
   time?: whisk_api_shared_v1_Time;
   date: whisk_api_shared_v1_Date;
   searches: whisk_api_user_v2_SearchRecipesResponse[];
@@ -898,7 +905,7 @@ export const whisk_api_user_v2_SearchRecipesResponse_MatchedIngredient_Recommend
 export type whisk_api_user_v2_SearchRecipesResponse_Empty = FieldEmpty;
 export const whisk_api_user_v2_SearchRecipesResponse_Empty: Field<whisk_api_user_v2_SearchRecipesResponse_Empty>;
 export type whisk_api_user_v2_SearchRecipesResponse_Hit = {
-  /** @deprecated */
+/** @deprecated */
   content?: whisk_api_user_v2_SearchRecipesResponse_MatchedIngredient;
   ingredients: whisk_api_user_v2_SearchRecipesResponse_MatchedIngredient[];
   mapIngredients: Record<string, whisk_api_user_v2_SearchRecipesResponse_MatchedIngredient_Recommendations>;
@@ -911,6 +918,8 @@ export const whisk_api_user_v2_SearchRecipesResponse_Height_Unit2: {
 };
 export type whisk_api_user_v2_SearchRecipesResponse_Height_Unit2 = Values<typeof whisk_api_user_v2_SearchRecipesResponse_Height_Unit2>;
 export type whisk_api_user_v2_SearchRecipesResponse_Height = FieldEmpty;
+/** If true, when this message is used as an optional field, do not wrap it in an `Option`.
+ This is equivalent of setting `(field).no_box` to true on each field with the message type. */
 export const whisk_api_user_v2_SearchRecipesResponse_Height: Field<whisk_api_user_v2_SearchRecipesResponse_Height>;
 export type whisk_api_user_v2_DeepCheck = {
   items: whisk_api_user_v2_SearchRecipesResponse_Hit[];
@@ -957,7 +966,7 @@ export const whisk_api_user_v2_SaveRecipeRequest: Field<whisk_api_user_v2_SaveRe
 export type whisk_api_user_v2_UpdateRecipeRequest = {
   recipeId: string;
   recipeMask?: google_protobuf_FieldMask;
-  /** possible values: payload, collection_ids */
+/** possible values: payload, collection_ids */
   updateMask?: google_protobuf_FieldMask;
   payload?: whisk_api_user_v2_User;
   collectionIds: string[];