In-line Proto Documentation in Generated Code.

Add in-line documentation present in the proto file into the generated code as a JSDoc comment; also prefixes the output with the same 'Generate Code' comment generated by protoc-js

client/protoc-gen-improbable-grpc-web/generated/_proto/proto/examplecom/simple_service_pb_service.d.ts

@@ -1,3 +1,5 @@
+// GENERATED CODE -- DO NOT EDIT!
+
 import * as proto_othercom_external_child_message_pb from "../../proto/othercom/external_child_message_pb";
 import * as google_protobuf_empty_pb from "google-protobuf/google/protobuf/empty_pb";
 import * as proto_examplecom_simple_service_pb from "../../proto/examplecom/simple_service_pb";
@@ -41,12 +43,21 @@ declare type SimpleServiceDelete = {
     requestType: proto_examplecom_simple_service_pb.UnaryRequest;
     responseType: proto_examplecom_simple_service_pb.UnaryResponse;
 };
+/**
+ * SimpleService is a simple grpc service.
+ */
 export declare class SimpleService {
     static readonly serviceName: string;
+    /**
+     * DoUnary is a unary gRPC service
+     */
     static readonly DoUnary: SimpleServiceDoUnary;
     static readonly DoServerStream: SimpleServiceDoServerStream;
     static readonly DoClientStream: SimpleServiceDoClientStream;
     static readonly DoBidiStream: SimpleServiceDoBidiStream;
+    /**
+     * checks that rpc methods that use reserved JS words don't generate invalid code
+     */
     static readonly Delete: SimpleServiceDelete;
 }
 export {};

client/protoc-gen-improbable-grpc-web/generated/_proto/proto/examplecom/simple_service_pb_service.js

@@ -1,12 +1,20 @@
+// GENERATED CODE -- DO NOT EDIT!
+
 "use strict";
 exports.__esModule = true;
 var proto_othercom_external_child_message_pb = require("../../proto/othercom/external_child_message_pb");
 var google_protobuf_empty_pb = require("google-protobuf/google/protobuf/empty_pb");
 var proto_examplecom_simple_service_pb = require("../../proto/examplecom/simple_service_pb");
+/**
+ * SimpleService is a simple grpc service.
+ */
 var SimpleService = /** @class */ (function () {
     function SimpleService() {
     }
     SimpleService.serviceName = "SimpleService";
+    /**
+     * DoUnary is a unary gRPC service
+     */
     SimpleService.DoUnary = {
         methodName: "DoUnary",
         service: SimpleService,
@@ -39,6 +47,9 @@ var SimpleService = /** @class */ (function () {
         requestType: proto_examplecom_simple_service_pb.StreamRequest,
         responseType: proto_othercom_external_child_message_pb.ExternalChildMessage
     };
+    /**
+     * checks that rpc methods that use reserved JS words don't generate invalid code
+     */
     SimpleService.Delete = {
         methodName: "Delete",
         service: SimpleService,

client/protoc-gen-improbable-grpc-web/generated/_proto/proto/othercom/external_child_message_pb_service.d.ts

@@ -1 +1,3 @@
+// GENERATED CODE -- DO NOT EDIT!
+
 export {};

client/protoc-gen-improbable-grpc-web/generated/_proto/proto/othercom/external_child_message_pb_service.js

@@ -1,2 +1,4 @@
+// GENERATED CODE -- DO NOT EDIT!
+
 "use strict";
 exports.__esModule = true;

client/protoc-gen-improbable-grpc-web/generated/_proto/proto/othercom/external_enum_pb_service.d.ts

@@ -1 +1,3 @@
+// GENERATED CODE -- DO NOT EDIT!
+
 export {};

client/protoc-gen-improbable-grpc-web/generated/_proto/proto/othercom/external_enum_pb_service.js

@@ -1,2 +1,4 @@
+// GENERATED CODE -- DO NOT EDIT!
+
 "use strict";
 exports.__esModule = true;

client/protoc-gen-improbable-grpc-web/proto/examplecom/simple_service.proto

@@ -19,7 +19,9 @@ message StreamRequest {
   string some_string = 1;
 }
 
+// SimpleService is a simple grpc service.
 service SimpleService {
+  // DoUnary is a unary gRPC service
   rpc DoUnary(UnaryRequest) returns (othercom.ExternalChildMessage) {}
   rpc DoServerStream(StreamRequest) returns (stream othercom.ExternalChildMessage) {}
   rpc DoClientStream(stream StreamRequest) returns (google.protobuf.Empty) {}

client/protoc-gen-improbable-grpc-web/src/codegen.ts

@@ -3,6 +3,7 @@ import {FileDescriptorProto} from "google-protobuf/google/protobuf/descriptor_pb
 import Project, {CodeBlockWriter} from "ts-morph";
 import * as path from "path";
 import {trimSuffix, makeImportTargetNamespace, getRelativePathToRoot, trimPrefix} from "./util";
+import {findCommentByPath} from "protoc-plugin";
 
 type GeneratedOutput = {
   name: string
@@ -38,7 +39,9 @@ export class GrpcWebCodeGenerator {
     return this.project.emitToMemory().getFiles().map(f => {
       return {
         name: trimPrefix(f.filePath, process.cwd()),
-        content: f.text
+        // Note the Generated Code is prefixed here to ensure if is the very first line in the
+        // output file; tsc will place code above it otherwise.
+        content: "// GENERATED CODE -- DO NOT EDIT!\n\n" + f.text
       }
     })
   }
@@ -128,12 +131,24 @@ class ServiceDefinitionBuilder {
   }
 
   private writeServiceClasses() {
+    let serviceIdx = 0;
+    const locations = this.fd.getSourceCodeInfo().getLocationList().map(l => l.toObject());
+
     for (const service of this.fd.getServiceList()) {
+      const serviceDescription = findCommentByPath([ 6, serviceIdx], locations);
+      if (serviceDescription) {
+        this.writeDocBlock(serviceDescription);
+      }
       this.w.writeLine(`export class ${service.getName()} {`);
       this.w.indentBlock(() => {
         this.w.writeLine(`static readonly serviceName: string = "${service.getName()}"`);
 
+        let methodIdx = 0;
         for (const method of service.getMethodList()) {
+          const methodDescription = findCommentByPath([ 6, serviceIdx, 2, methodIdx], locations);
+          if (methodDescription) {
+            this.writeDocBlock(methodDescription);
+          }
           this.w.writeLine(`static readonly ${method.getName()}: ${service.getName()}${method.getName()} = {`);
           this.w.indentBlock(() => {
             this.w.indentBlock(() => {
@@ -146,11 +161,21 @@ class ServiceDefinitionBuilder {
             });
           });
           this.w.writeLine(`}`);
+          methodIdx++;
         }
 
       });
       this.w.writeLine(`}`);
       this.w.blankLine();
+      serviceIdx++;
+    }
+  }
+
+  private writeDocBlock(comment: string) {
+    this.w.writeLine('/**');
+    for (const line of comment.split("\n")) {
+      this.w.writeLine(` * ${line}`);
     }
+    this.w.writeLine(' */');
   }
 }

client/protoc-gen-improbable-grpc-web/src/index.ts

@@ -1,17 +1,13 @@
 import {ExportMap} from "./exportmap";
 import {GrpcWebCodeGenerator} from "./codegen";
 import {
-  CodeGeneratorRequest as pb_CodeGeneratorRequest,
-  CodeGeneratorResponse as pb_CodeGeneratorResponse
-} from "google-protobuf/google/protobuf/compiler/plugin_pb";
-
-// TODO: Publish @types for protoc-plugin
-declare function require(path: string): any;
-const {CodeGeneratorRequest, CodeGeneratorResponse, CodeGeneratorResponseError} = require('protoc-plugin')
+  CodeGeneratorRequest, CodeGeneratorResponse, CodeGeneratorResponseError,
+  OutputFile
+} from "protoc-plugin";
 
 CodeGeneratorRequest()
-  .then((req: pb_CodeGeneratorRequest)  => {
-    const output: pb_CodeGeneratorResponse.File.AsObject[] = [];
+  .then((req)  => {
+    const output: OutputFile[] = [];
     const exportMap = new ExportMap(req.getProtoFileList());
     const codeGen = new GrpcWebCodeGenerator(exportMap);