refactor: improve comments

proto/whisk/api/shared/v1/complex.proto

@@ -3,9 +3,18 @@ syntax = "proto3";
 package whisk.api.shared.v1;
 
 message Test {
+  /** Multi
+  line /** test *\/  */
   string string = 1;
+  //  Up lime
   uint32 uint32 = 2;
-  Inner inner = 3;
+  Inner inner = 3; // Side line
+  /**
+   * Represents a book.
+   * @constructor
+   * @param {string} title - The title of the book.
+   * @param {string} author - The author of the book.
+   */
   float float = 4;
 
   message Inner {
@@ -20,6 +29,7 @@ message Test {
     }
   }
 
+  // Describes how items
   enum Enum {
     ONE = 0;
     TWO = 1;

proto/whisk/api/user/v2/user.proto

@@ -44,10 +44,13 @@ message PersonalDetails {
   message HealthGoals { repeated HealthGoal list = 1; }
 }
 
+// Describes goals
 enum HealthGoal {
   HEALTH_GOAL_INVALID = 0;
+  // Loss
   HEALTH_GOAL_WEIGHT_LOSS = 1;
-  HEALTH_GOAL_WEIGHT_GAIN = 2;
+  HEALTH_GOAL_WEIGHT_GAIN = 2; // Gain
+  /** Sleep */
   HEALTH_GOAL_BETTER_SLEEP = 3;
   HEALTH_GOAL_INCREASE_ENERGY = 4;
 }
@@ -74,6 +77,7 @@ message Weight {
   Unit unit = 2;
 }
 
+// Example food
 message FoodPreferences {
   string diets = 1;
   repeated string avoidance_list = 2;

proto/whisk/api/user/v2/user_api.proto

@@ -10,7 +10,9 @@ import "google/api/field_mask.proto";
 import "google/api/empty.proto";
 import "whisk/api/user/v2/user.proto";
 
+// Use api example
 service UserAPI {
+  // Get My profile
   rpc GetMe(GetMeRequest) returns (GetMeResponse) {
     option (google.api.http) = {
       get: "/user/v2/me"

src/generator/enum.ts

@@ -1,4 +1,4 @@
-import { isNumber } from '@whisklabs/typeguards';
+import { isNumber, isText } from '@whisklabs/typeguards';
 
 import { Parser } from '../parser';
 import { MakeOuts } from './generator';
@@ -16,15 +16,23 @@ function enu(pack: string, out: MakeOuts, item: Parser.Enum) {
   const cID = checkSame(out, 'id');
   const cName = checkSame(out, 'name');
 
+  if (isText(item.comment)) {
+    out.dts.push(`/** ${item.comment.trim()} */`);
+  }
+
   out.js.push(`export const ${eName} = {`);
   out.dts.push(`export const ${eName}: {`);
 
   for (const field in item.values) {
     const val = item.values[field].value;
+    const comment = item.values[field].comment;
     if (isNumber(val) && !isNaN(val) && !isInvalidEnumField(field, val)) {
       cID(val, `${pack}.${field}`);
       cName(field, `${pack}.${field}`);
       out.js.push(`  ${field}: ${val},`);
+      if (isText(comment)) {
+        out.dts.push(`/** ${comment} */`);
+      }
       out.dts.push(`  readonly ${field}: ${val},`);
     }
   }

src/generator/message.ts

@@ -74,11 +74,7 @@ function message(
         oneof[field.oneof] = oneof[field.oneof] ?? [];
         oneof[field.oneof].push(field);
       } else {
-        if (isText(field.options.deprecated)) {
-          out.dts.push(`  /**  @deprecated ${field.options.deprecated} */`);
-        } else if (field.options.deprecated === true) {
-          out.dts.push('  /**  @deprecated */');
-        }
+        getComment(field, out);
 
         const fieldName = getField(
           field,
@@ -109,11 +105,7 @@ function message(
         const find = list.find(i => i.name === field.map?.to || i.name === field.type);
         const fieldPack = isPresent(find) ? find.pack : pack;
 
-        if (isText(field.options.deprecated)) {
-          out.dts.push(`  /**  @deprecated ${field.options.deprecated} */`);
-        } else if (field.options.deprecated === true) {
-          out.dts.push('  /**  @deprecated */');
-        }
+        getComment(field, out);
 
         const naming = camelCase(field.name);
 
@@ -140,10 +132,29 @@ function message(
     out.dts.push(`export type ${baseName} = FieldEmpty;`);
   }
 
+  if (isText(item.comment)) {
+    out.dts.push(`/** ${item.comment.trim()} */`);
+  }
   out.dts.push(`export const ${baseName}: Field<${baseName}>;`);
   out.js.push(`export function ${baseName} () { return [`);
   for (const field of runtime) {
     out.js.push(field);
   }
   out.js.push(']; }');
 }
+function getComment(field: Parser.Field, out: MakeOuts) {
+  let comment = '';
+  if (isText(field.options.deprecated)) {
+    comment += `@deprecated ${field.options.deprecated}\n`;
+  } else if (field.options.deprecated === true) {
+    comment += '@deprecated\n';
+  }
+
+  if (isText(field.comment)) {
+    comment += field.comment;
+  }
+
+  if (isText(comment)) {
+    out.dts.push(`  /** ${comment.trim()} */`);
+  }
+}

src/generator/service.ts

@@ -1,3 +1,5 @@
+import { isText } from '@whisklabs/typeguards';
+
 import { Parser } from '../parser';
 import { pathField } from './field';
 import { MakeOuts } from './generator';
@@ -22,6 +24,9 @@ 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(`export type ${sName} = Service<Field<${input}>, Field<${output}>>;`);
   out.dts.push(`export const ${sName}: ${sName};`);
 

src/parser/tokens/enums.ts

@@ -1,4 +1,4 @@
-import { next, setComment, writeComment } from '../comment';
+import { next, writeComment } from '../comment';
 import { Thrower } from '../thrower';
 import { Enum } from '../types';
 import { ch, check, cut, insertOption, semicolon } from '../utils';
@@ -38,7 +38,7 @@ export function ParseEnums(tokens: string[]) {
     options: {},
   };
 
-  setComment(en);
+  writeComment(en);
 
   cut(tokens, 3);
 

src/parser/tokens/message.ts

@@ -1,6 +1,6 @@
 import { isObject } from '@whisklabs/typeguards';
 
-import { next, setComment, writeComment } from '../comment';
+import { next, writeComment } from '../comment';
 import { Thrower } from '../thrower';
 import { Message } from '../types';
 import { ch, check, cut, insertOption } from '../utils';
@@ -31,7 +31,7 @@ export function MessageBody(tokens: string[], name: string) {
     reserved: [],
   };
 
-  setComment(message);
+  writeComment(message);
 
   while (tokens.length > 0) {
     switch (next(tokens)) {

tests/parser/success/comments.json

@@ -62,7 +62,7 @@
           "repeated": false,
           "optional": false,
           "options": {},
-          "comment": "Multi-line comment\n\n"
+          "comment": "\n"
         },
         {
           "name": "end",
@@ -87,7 +87,8 @@
       ],
       "extends": [],
       "extensions": [],
-      "reserved": []
+      "reserved": [],
+      "comment": "Multi-line comment"
     },
     {
       "name": "A",

tests/parser/success/full.json

@@ -40,7 +40,8 @@
           "comment": " ONE means 1"
         }
       },
-      "options": {}
+      "options": {},
+      "comment": " NumericEnum is one or zero."
     }
   ],
   "messages": [
@@ -78,7 +79,8 @@
           ],
           "extends": [],
           "extensions": [],
-          "reserved": []
+          "reserved": [],
+          "comment": "fgfg\n    dfv "
         }
       ],
       "fields": [
@@ -95,7 +97,7 @@
       "extends": [],
       "extensions": [],
       "reserved": [],
-      "comment": " example file\n example file"
+      "comment": " example file"
     },
     {
       "name": "Person",
@@ -232,8 +234,7 @@
           "required": true,
           "repeated": false,
           "optional": false,
-          "options": {},
-          "comment": " example file"
+          "options": {}
         },
         {
           "name": "age",
@@ -258,7 +259,8 @@
       ],
       "extends": [],
       "extensions": [],
-      "reserved": []
+      "reserved": [],
+      "comment": " example file"
     },
     {
       "name": "TestItem",