Generate documentation from proto comments (#743)

Motivation:

We have access to the underlying comments associated with RPCs in the
protobuf definition. These often explain what each RPC does and can have
great value to the user.

Modifications:

- Generate documentation for client stubs and server provider protocol
  based on the source comments in the proto file.
- Re-generate code.

Result:

- The generate code has more helpful documentation

Sources/protoc-gen-grpc-swift/Generator-Client.swift

@@ -70,9 +70,10 @@ extension Generator {
 
     for method in service.methods {
       self.method = method
-      switch streamingType(method) {
+      let streamType = streamingType(self.method)
+      switch streamType {
       case .unary:
-        println("/// Asynchronous unary call to \(method.name).")
+        println(self.method.documentation(streamingType: streamType), newline: false)
         println("///")
         printParameters()
         printRequestParameter()
@@ -87,7 +88,7 @@ extension Generator {
         println("}")
 
       case .serverStreaming:
-        println("/// Asynchronous server-streaming call to \(method.name).")
+        println(self.method.documentation(streamingType: streamType), newline: false)
         println("///")
         printParameters()
         printRequestParameter()
@@ -104,7 +105,7 @@ extension Generator {
         println("}")
 
       case .clientStreaming:
-        println("/// Asynchronous client-streaming call to \(method.name).")
+        println(self.method.documentation(streamingType: streamType), newline: false)
         println("///")
         printClientStreamingDetails()
         println("///")
@@ -119,7 +120,7 @@ extension Generator {
         println("}")
 
       case .bidirectionalStreaming:
-        println("/// Asynchronous bidirectional-streaming call to \(method.name).")
+        println(self.method.documentation(streamingType: streamType), newline: false)
         println("///")
         printClientStreamingDetails()
         println("///")
@@ -162,3 +163,35 @@ extension Generator {
     println("///   - handler: A closure called when each response is received from the server.")
   }
 }
+
+fileprivate extension StreamingType {
+  var name: String {
+    switch self {
+    case .unary:
+      return "Unary"
+    case .clientStreaming:
+      return "Client streaming"
+    case .serverStreaming:
+      return "Server streaming"
+    case .bidirectionalStreaming:
+      return "Bidirectional streaming"
+    }
+  }
+}
+
+extension MethodDescriptor {
+  var documentation: String? {
+    let comments = self.protoSourceComments(commentPrefix: "")
+    return comments.isEmpty ? nil : comments
+  }
+
+  fileprivate func documentation(streamingType: StreamingType) -> String {
+    let sourceComments = self.protoSourceComments()
+
+    if sourceComments.isEmpty {
+      return "/// \(streamingType.name) call to \(self.name)\n"  // comments end with "\n" already.
+    } else {
+      return sourceComments  // already prefixed with "///"
+    }
+  }
+}

Sources/protoc-gen-grpc-swift/Generator-Server.swift

@@ -31,12 +31,16 @@ extension Generator {
       
       switch streamingType(method) {
       case .unary:
+        println(self.method.protoSourceComments(), newline: false)
         println("func \(methodFunctionName)(request: \(methodInputName), context: StatusOnlyCallContext) -> EventLoopFuture<\(methodOutputName)>")
       case .serverStreaming:
+        println(self.method.protoSourceComments(), newline: false)
         println("func \(methodFunctionName)(request: \(methodInputName), context: StreamingResponseCallContext<\(methodOutputName)>) -> EventLoopFuture<GRPCStatus>")
       case .clientStreaming:
+        println(self.method.protoSourceComments(), newline: false)
         println("func \(methodFunctionName)(context: UnaryResponseCallContext<\(methodOutputName)>) -> EventLoopFuture<(StreamEvent<\(methodInputName)>) -> Void>")
       case .bidirectionalStreaming:
+        println(self.method.protoSourceComments(), newline: false)
         println("func \(methodFunctionName)(context: StreamingResponseCallContext<\(methodOutputName)>) -> EventLoopFuture<(StreamEvent<\(methodInputName)>) -> Void>")
       }
     }

Sources/protoc-gen-grpc-swift/Generator.swift

@@ -41,9 +41,11 @@ class Generator {
     return printer.content
   }
 
-  internal func println(_ text: String = "") {
+  internal func println(_ text: String = "", newline: Bool = true) {
     printer.print(text)
-    printer.print("\n")
+    if newline {
+      printer.print("\n")
+    }
   }
 
   internal func indent() {
@@ -122,5 +124,4 @@ class Generator {
     self.println()
     self.printProtobufExtensions()
   }
-
 }