feat: add jsdoc comment for parameters (#94)

* logic for printing comments for parameters

* render comment for parameters

* align asterisks

* escape */ to break the comment

* actual type

* update baseline

* replace all */

* add unit test for replace all helper function

* render real js type

* update baseline

* add request object comment

* add return comment

* reformat comments

* gts

* add return comments for simple method

* return comment for all methods

* update baseline test

* feedback

* update baseline

* simplify logic for printing return comments

templates/typescript_gapic/_util.njk

@@ -26,3 +26,104 @@ limitations under the License.
             {{ chain }}.{{ method.headerRequestParams.slice(-1)[0] }} = '';
 {%- endif %}
 {%- endmacro -%}
+
+{%- macro printCommentsForParams(method) -%}
+{%- set commentsMap = method.paramComment -%}
+{%- for oneComment in commentsMap -%}
+{%- set type = oneComment.paramType -%}
+{%- if type.startsWith('.') %}
+ * @param { {{- type.substring(1) -}} } request.{{ oneComment.paramName }}
+{%- else %}
+ * @param { {{- convertParamType(oneComment.paramType) -}} } request.{{ oneComment.paramName }}
+{%- endif -%}
+{%- set lines = oneComment.comments -%}
+{%- for line in lines %} 
+ *  {{ line.replaceAll('*/', '* /') | safe}} 
+{%- endfor -%}
+{%- endfor -%}
+{%- endmacro -%}
+
+{%- macro printCommentsForMethod(method) -%}
+{%- set lines = method.comments -%}
+{% for line in lines %}
+ *{{ line | safe}}
+{%- endfor %}
+{%- endmacro -%}
+
+{%- macro printCommentsForService(service) -%}
+{%- set lines = service.comments -%}
+{% for line in lines %}
+   * {{ line | safe}}
+{%- endfor %}
+{%- endmacro -%}
+
+{%- macro printRequest() %}
+ * @param {Object} request
+ *   The request object that will be sent.
+{%- endmacro -%}
+
+{%- macro printReturn(method, service) -%}
+{%- if method.longRunning %}
+{{- printReturnSimpleMethod(method) }}
+{%- elif method.serverStreaming and method.clientStreaming %}
+{{- printReturnBidiStreamingMethod(method) }}
+{%- elif method in service.paging %}
+{{- printReturnPagingServerMethod(method) }}
+{%- elif method.serverStreaming %}
+{{- printReturnPagingServerMethod(method) }}
+{%- elif method.clientStreaming %}
+{{- printReturnClientStreamingMethod(method) }}
+{%- else %}
+{{- printReturnSimpleMethod(method) }}
+{%- endif -%}
+{%- endmacro -%}
+
+{%- macro printReturnSimpleMethod(method) %}
+ * @returns {Promise} - The promise which resolves to an array.
+ *   The first element of the array is an object representing [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}}.
+ *   The promise has a method named "cancel" which cancels the ongoing API call.
+{%- endmacro -%}
+
+{%- macro printReturnPagingServerMethod(method) %}
+ * @returns {Promise} - The promise which resolves to an array.
+ *   The first element of the array is an object representing [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}}.
+ *   
+ *   When autoPaginate: false is specified through options, the array has three elements.
+ *   The first element is Array of [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}} in a single response.
+ *   The second element is the next request object if the response
+ *   indicates the next page exists, or null. The third element is
+ *   an object representing [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}}.
+ *
+ *   The promise has a method named "cancel" which cancels the ongoing API call.
+{%- endmacro -%}
+
+
+{%- macro printReturnClientStreamingMethod(method) %}
+ * @returns {Stream} - A writable stream which accepts objects representing 
+ * [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}}.
+{%- endmacro -%}
+
+{%- macro printReturnBidiStreamingMethod(method) %}
+ * @returns {Stream} 
+ *   An object stream which is both readable and writable. It accepts objects
+ *   representing [[{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}} for write() method, and
+ *   will emit objects representing [{{- toMessageName(method.outputType) -}}]{@link {{ method.outputType.substring(1) }}} on 'data' event asynchronously.
+{%- endmacro -%}
+
+{%- macro toMessageName(messageType) -%}
+{%- set arr = messageType.split('.') %}
+{{- arr[arr.length - 1] -}}
+{%- endmacro -%}
+
+{%- macro convertParamType(paramType) -%}
+{%- if paramType.includes('TYPE_BYTES') %}
+{%- set type = paramType.replace('TYPE_BYTES', 'Buffer') %}
+{%- elif paramType.includes('TYPE_BOOL') %}
+{%- set type = paramType.replace('TYPE_BOOL', 'boolean') %}
+{%- elif paramType.includes('TYPE_STRING') %}
+{%- set type = paramType.replace('TYPE_STRING', 'string') %}
+{%- else %}
+{%- set type = 'number' %}
+{%- endif %}
+          {{- type -}}
+{%- endmacro -%}

templates/typescript_gapic/src/$version/$service_client.ts.njk

@@ -17,6 +17,7 @@ limitations under the License.
 -#}
 {% import "../../_license.njk" as license -%}
 {{license.license()}}
+{% import "../../_util.njk" as util -%}
 import * as gax from 'google-gax';
 import * as path from 'path';
 
@@ -67,9 +68,9 @@ export interface PaginationResponse<
 }
 {% endif %}
 export class {{ service.name }}Client {
-  /*
-  {{ service.comments }}
-  */
+  /**
+    {{- util.printCommentsForService(service) }}
+   */
   private _descriptors: Descriptors = {page: {}, stream: {}, longrunning: {}};
   private _innerApiCalls: {[name: string]: Function};
   {%- if (service.pathTemplates.length > 0) %}
@@ -337,9 +338,12 @@ export class {{ service.name }}Client {
   // -------------------
 
 {%- for method in service.simpleMethods %}
-  /*
-  {{ method.comments }} 
-  */
+/**
+  {{- util.printCommentsForMethod(method) }}
+  {{- util.printRequest() -}}
+  {{- util.printCommentsForParams(method) -}}
+  {{- util.printReturn(method, service) }}
+ */
   {{ method.name.toCamelCase() }}(
       request: protosTypes{{ method.inputInterface }},
       options?: gax.CallOptions):
@@ -390,9 +394,12 @@ export class {{ service.name }}Client {
   } 
 {%- endfor %}
 {% for method in service.streaming %}
-  /*
-  {{ method.comments }} 
-  */
+/**
+  {{- util.printCommentsForMethod(method) }}
+  {{- util.printRequest() -}}
+  {{- util.printCommentsForParams(method) -}}
+  {{- util.printReturn(method, service) }}
+ */
 {%- if method.serverStreaming and method.clientStreaming %}
   {{ method.name.toCamelCase() }}(
       options?: gax.CallOptions):
@@ -439,9 +446,12 @@ export class {{ service.name }}Client {
 {%- endif %}
 {% endfor %}
 {%- for method in service.longRunning %}
-  /*
-  {{ method.comments }} 
-  */
+/**
+  {{- util.printCommentsForMethod(method) }}
+  {{- util.printRequest() -}}
+  {{- util.printCommentsForParams(method) -}}
+  {{- util.printReturn(method, service) }}
+ */
   {{ method.name.toCamelCase() }}(
       request: protosTypes{{ method.inputInterface }},
       options?: gax.CallOptions):
@@ -492,9 +502,12 @@ export class {{ service.name }}Client {
   } 
 {%- endfor %}
 {%- for method in service.paging %}
-  /*
-  {{ method.comments }} 
-  */
+/**
+  {{- util.printCommentsForMethod(method) }}
+  {{- util.printRequest() -}}
+  {{- util.printCommentsForParams(method) -}}
+  {{- util.printReturn(method, service) }}
+ */
   {{ method.name.toCamelCase() }}(
       request: protosTypes{{ method.inputInterface }},
       options?: gax.CallOptions):

typescript/index.d.ts

@@ -19,6 +19,7 @@ interface String {
   toPascalCase(): string;
   toKebabCase(): string;
   toSnakeCase(): string;
+  replaceAll(this: string, search: string, replacement: string): string;
 }
 
 interface Array<T> {

typescript/src/schema/comments.ts

@@ -13,8 +13,20 @@
 // limitations under the License.
 
 import * as plugin from '../../../pbjs-genfiles/plugin';
+
+// For one comment in service and method level, paramName & paramName will be ''.
+// Only field has name and type of parameters.
+export interface Comment {
+  paramName: string;
+  paramType: string;
+  comments: string[];
+}
+
+// For service, one item will be <serviceName, comment>
+// For method, one item will be <serviceName:methodName, comment>
+// For field, one item will be <messageInputType:fieldname, comment>
 export interface Comments {
-  [name: string]: string;
+  [name: string]: Comment;
 }
 
 export class CommentsMap {
@@ -37,20 +49,88 @@ export class CommentsMap {
           const p = location.path!;
           if (p.length === 2 && p[0] === 6) {
             if (fd.service && fd.service[p[1]] && fd.service[p[1]].name) {
-              commentsMap[fd.service[p[1]].name! + 'Service'] =
-                location.leadingComments || '';
+              const serviceName = fd.service[p[1]].name!;
+              const comments = (location.leadingComments || '')
+                .split('\n')
+                .slice(0, -1);
+              const serviceComment: Comment = {
+                paramName: '',
+                paramType: '',
+                comments,
+              };
+              commentsMap[serviceName] = serviceComment;
             }
-          } else if (p.length === 4 && p[2] === 2) {
+          } else if (p.length === 4 && p[2] === 2 && p[0] === 6) {
             if (
               fd.service &&
               fd.service[p[1]] &&
               fd.service[p[1]].method &&
               fd.service[p[1]].method![p[3]] &&
               fd.service[p[1]].method![p[3]].name
             ) {
-              const name = fd.service[p[1]].method![p[3]].name!;
-              if (!commentsMap[name]) {
-                commentsMap[name] = location.leadingComments || '';
+              const serviceName = fd.service[p[1]].name!;
+              // add method comment into the map
+              const methodName = fd.service[p[1]].method![p[3]].name!;
+              if (!commentsMap[methodName]) {
+                const comments = (location.leadingComments || '').split('\n');
+                const key = serviceName + ':' + methodName;
+                const methodComment: Comment = {
+                  paramName: '',
+                  paramType: '',
+                  comments,
+                };
+                commentsMap[key] = methodComment;
+              }
+            }
+          } else if (p.length === 4 && p[0] === 4 && p[2] === 2) {
+            // This contains a field's information
+            // example, this path:
+            //   [ 4, 3, 2, 7, 1 ]
+            // refers to:
+            //   file.message_type(3)  // 4, 3
+            //       .field(7)         // 2, 7
+            //       .name()           // 1
+            // This is because FileDescriptorProto.message_type has field number 4:
+            //   repeated DescriptorProto message_type = 4;
+            // and DescriptorProto.field has field number 2:
+            //   repeated FieldDescriptorProto field = 2;
+            // and FieldDescriptorProto.name has field number 1:
+            //   optional string name = 1;
+            if (
+              fd.messageType &&
+              fd.messageType[p[1]] &&
+              fd.messageType[p[1]].field &&
+              fd.messageType[p[1]].field![p[3]]
+            ) {
+              const messageType = fd.messageType[p[1]].name;
+              const field = fd.messageType[p[1]].field![p[3]];
+              // console.warn(field);
+              if (field) {
+                //Type Enum: TYPE_STRING, TYPE_BOOL, etc.
+                let paramType =
+                  plugin.google.protobuf.FieldDescriptorProto.Type[field.type!];
+                // If field.label is 'REPEATED' then the paramType is an array.
+                if (field.label === 3) {
+                  paramType += '[]';
+                }
+                const paramName = field.name || '';
+                if (
+                  paramType === 'TYPE_MESSAGE' ||
+                  paramType === 'TYPE_ENUM' ||
+                  paramType === 'TYPE_GROUP'
+                ) {
+                  paramType = field.typeName!;
+                }
+                const comments = (location.leadingComments || '')
+                  .split('\n')
+                  .slice(0, -1);
+                const fieldComment: Comment = {
+                  paramName,
+                  paramType,
+                  comments,
+                };
+                const key = messageType + ':' + field.name;
+                commentsMap[key] = fieldComment;
               }
             }
           }
@@ -63,9 +143,18 @@ export class CommentsMap {
     return this.comments;
   }
   getServiceComment(serviceName: string) {
-    return this.comments[serviceName + 'Service'].trim();
+    return this.comments[serviceName]
+      ? this.comments[serviceName].comments
+      : [];
+  }
+  getMethodComments(serviceName: string, methodName: string) {
+    const key = serviceName + ':' + methodName;
+    return this.comments[key] ? this.comments[key].comments : [];
   }
-  getMethodComments(methodName: string): string {
-    return this.comments[methodName].trim();
+  getParamComments(messageName: string, fieldName: string): Comment {
+    const key = messageName + ':' + fieldName;
+    return this.comments[key]
+      ? this.comments[key]
+      : { paramName: '', paramType: '', comments: [] };
   }
 }