chore: add comments on service & method level (#66)

* add comments on service & method level

* move comments to comment.ts

* move method to comment.ts

* clean

* make arg look similar for method & service

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

@@ -50,6 +50,9 @@ export interface PaginationResponse<
 }
 {% endif %}
 export class {{ service.name }}Client {
+  /*
+  {{ service.comments }}
+  */
   private _descriptors: Descriptors = {page: {}, stream: {}, longrunning: {}};
   private _innerApiCalls: {[name: string]: Function};
   auth: gax.GoogleAuth;
@@ -303,6 +306,9 @@ export class {{ service.name }}Client {
   // -------------------
 
 {%- for method in service.simpleMethods %}
+  /*
+  {{ method.comments }} 
+  */
   {{ method.name.toCamelCase() }}(
       request: protosTypes{{ method.inputInterface }},
       options?: gax.CallOptions):
@@ -341,6 +347,9 @@ export class {{ service.name }}Client {
   } 
 {%- endfor %}
 {% for method in service.streaming %}
+  /*
+  {{ method.comments }} 
+  */
 {%- if method.serverStreaming and method.clientStreaming %}
   {{ method.name.toCamelCase() }}(
       options?: gax.CallOptions):
@@ -387,6 +396,9 @@ export class {{ service.name }}Client {
 {%- endif %}
 {% endfor %}
 {%- for method in service.longRunning %}
+  /*
+  {{ method.comments }} 
+  */
   {{ method.name.toCamelCase() }}(
       request: protosTypes{{ method.inputInterface }},
       options?: gax.CallOptions):
@@ -425,6 +437,9 @@ export class {{ service.name }}Client {
   } 
 {%- endfor %}
 {%- for method in service.paging %}
+  /*
+  {{ method.comments }} 
+  */
   {{ method.name.toCamelCase() }}(
       request: protosTypes{{ method.inputInterface }},
       options?: gax.CallOptions):

typescript/src/schema/comments.ts

@@ -0,0 +1,57 @@
+import * as plugin from '../../../pbjs-genfiles/plugin';
+export interface Comments {
+  [name: string]: string;
+}
+
+export class CommentsMap {
+  comments: Comments = {};
+
+  constructor(fd: plugin.google.protobuf.IFileDescriptorProto) {
+    const commentsMap: Comments = {};
+    if (fd && fd.sourceCodeInfo && fd.sourceCodeInfo.location) {
+      const locations = fd.sourceCodeInfo.location;
+      locations.forEach(location => {
+        if (location.leadingComments !== null) {
+          // p is an array with format [f1, i1, f2, i2, ...]
+          // - f1 refers to the protobuf field tag
+          // - if field refer to by f1 is a slice, i1 refers to an element in that slice
+          // - f2 and i2 works recursively.
+          // So, [6, x] refers to the xth service defined in the file,
+          // since the field tag of Service is 6.
+          // [6, x, 2, y] refers to the yth method in that service,
+          // since the field tag of Method is 2.
+          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 || '';
+            }
+          } else if (p.length === 4 && p[2] === 2) {
+            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 || '';
+              }
+            }
+          }
+        }
+      });
+      this.comments = commentsMap;
+    }
+  }
+  getCommentsMap() {
+    return this.comments;
+  }
+  getServiceComment(serviceName: string) {
+    return this.comments[serviceName + 'Service'].trim();
+  }
+  getMethodComments(methodName: string): string {
+    return this.comments[methodName].trim();
+  }
+}

typescript/src/schema/proto.ts

@@ -1,7 +1,5 @@
-import { ENGINE_METHOD_DIGESTS } from 'constants';
-import { NEG_ONE } from 'long';
-
 import * as plugin from '../../../pbjs-genfiles/plugin';
+import { CommentsMap } from './comments';
 
 interface MethodDescriptorProto
   extends plugin.google.protobuf.IMethodDescriptorProto {
@@ -18,6 +16,7 @@ interface MethodDescriptorProto
   pagingResponseType?: string;
   inputInterface: string;
   outputInterface: string;
+  comments: string;
 }
 
 interface ServiceDescriptorProto
@@ -33,6 +32,7 @@ interface ServiceDescriptorProto
   hostname: string;
   port: number;
   oauthScopes: string[];
+  comments: string;
 }
 
 export interface ServicesMap {
@@ -162,7 +162,11 @@ function toLRInterface(type: string, inputType: string) {
   return inputType.replace(/\.([^.]+)$/, '.I' + type);
 }
 
-function augmentMethod(messages: MessagesMap, method: MethodDescriptorProto) {
+function augmentMethod(
+  messages: MessagesMap,
+  method: MethodDescriptorProto,
+  commentsMap: CommentsMap
+) {
   method = Object.assign(
     {
       idempotence: idempotence(method),
@@ -174,6 +178,7 @@ function augmentMethod(messages: MessagesMap, method: MethodDescriptorProto) {
       pagingResponseType: pagingResponseType(messages, method),
       inputInterface: toInterface(method.inputType!),
       outputInterface: toInterface(method.outputType!),
+      comments: commentsMap.getMethodComments(method.name!),
     },
     method
   ) as MethodDescriptorProto;
@@ -182,11 +187,13 @@ function augmentMethod(messages: MessagesMap, method: MethodDescriptorProto) {
 
 function augmentService(
   messages: MessagesMap,
-  service: plugin.google.protobuf.IServiceDescriptorProto
+  service: plugin.google.protobuf.IServiceDescriptorProto,
+  commentsMap: CommentsMap
 ) {
   const augmentedService = service as ServiceDescriptorProto;
+  augmentedService.comments = commentsMap.getServiceComment(service.name!);
   augmentedService.method = augmentedService.method.map(method =>
-    augmentMethod(messages, method)
+    augmentMethod(messages, method, commentsMap)
   );
   augmentedService.simpleMethods = augmentedService.method.filter(
     method =>
@@ -243,6 +250,7 @@ export class Proto {
   messages: MessagesMap = {};
   enums: EnumsMap = {};
   fileToGenerate: boolean;
+  commentsMap: CommentsMap;
   // TODO: need to store metadata? address?
 
   constructor(
@@ -278,10 +286,10 @@ export class Proto {
     this.fileToGenerate = fd.package
       ? fd.package.startsWith(packageName)
       : false;
-
+    this.commentsMap = new CommentsMap(fd);
     this.services = fd.service
       .filter(service => service.name)
-      .map(service => augmentService(this.messages, service))
+      .map(service => augmentService(this.messages, service, this.commentsMap))
       .reduce(
         (map, service) => {
           map[service.name!] = service;