Add documentation to generated code (#2133)

Motivation:

The generated code doesn't consistently include documentation from the
source IDL. It also doesn't explain the difference between each of the
generated protocols and when to use them.

Modifications:

Add documentation to the generated code, and where possible, also
include any documentation from the source IDL.

Result:

Better documented generated code

Author: glbrntt

Sources/GRPCCodeGen/Internal/StructuredSwift+Client.swift

@@ -210,7 +210,7 @@ extension ProtocolDescription {
       conformances: ["Sendable"],
       members: methods.map { method in
         .commentable(
-          .preFormatted(method.documentation),
+          .preFormatted(docs(for: method)),
           .function(
             signature: .clientMethod(
               name: method.name.generatedLowerCase,
@@ -251,16 +251,19 @@ extension ExtensionDescription {
     ExtensionDescription(
       onType: name,
       declarations: methods.map { method in
-        .function(
-          .clientMethodWithDefaults(
-            accessLevel: accessLevel,
-            name: method.name.generatedLowerCase,
-            input: method.inputType,
-            output: method.outputType,
-            streamingInput: method.isInputStreaming,
-            streamingOutput: method.isOutputStreaming,
-            serializer: .identifierPattern(serializer(method.inputType)),
-            deserializer: .identifierPattern(deserializer(method.outputType))
+        .commentable(
+          .preFormatted(docs(for: method, serializers: false)),
+          .function(
+            .clientMethodWithDefaults(
+              accessLevel: accessLevel,
+              name: method.name.generatedLowerCase,
+              input: method.inputType,
+              output: method.outputType,
+              streamingInput: method.isInputStreaming,
+              streamingOutput: method.isOutputStreaming,
+              serializer: .identifierPattern(serializer(method.inputType)),
+              deserializer: .identifierPattern(deserializer(method.outputType))
+            )
           )
         )
       }
@@ -495,11 +498,11 @@ extension ExtensionDescription {
     on extensionName: String,
     methods: [MethodDescriptor]
   ) -> ExtensionDescription {
-    ExtensionDescription(
+    return ExtensionDescription(
       onType: extensionName,
       declarations: methods.map { method in
         .commentable(
-          .preFormatted(method.documentation),
+          .preFormatted(explodedDocs(for: method)),
           .function(
             .clientMethodExploded(
               accessLevel: accessLevel,
@@ -665,26 +668,36 @@ extension StructDescription {
       conformances: [clientProtocol],
       members: [
         .variable(accessModifier: .private, kind: .let, left: "client", type: .grpcClient),
-        .function(
-          accessModifier: accessLevel,
-          kind: .initializer,
-          parameters: [
-            ParameterDescription(label: "wrapping", name: "client", type: .grpcClient)
-          ],
-          whereClause: nil,
-          body: [
-            .expression(
-              .assignment(
-                left: .identifierPattern("self").dot("client"),
-                right: .identifierPattern("client")
+        .commentable(
+          .preFormatted(
+            """
+            /// Creates a new client wrapping the provided `GRPCCore.GRPCClient`.
+            ///
+            /// - Parameters:
+            ///   - client: A `GRPCCore.GRPCClient` providing a communication channel to the service.
+            """
+          ),
+          .function(
+            accessModifier: accessLevel,
+            kind: .initializer,
+            parameters: [
+              ParameterDescription(label: "wrapping", name: "client", type: .grpcClient)
+            ],
+            whereClause: nil,
+            body: [
+              .expression(
+                .assignment(
+                  left: .identifierPattern("self").dot("client"),
+                  right: .identifierPattern("client")
+                )
               )
-            )
-          ]
+            ]
+          )
         ),
       ]
         + methods.map { method in
           .commentable(
-            .preFormatted(method.documentation),
+            .preFormatted(docs(for: method)),
             .function(
               .clientMethod(
                 accessLevel: accessLevel,
@@ -702,3 +715,82 @@ extension StructDescription {
     )
   }
 }
+
+private func docs(
+  for method: MethodDescriptor,
+  serializers includeSerializers: Bool = true
+) -> String {
+  let summary = "/// Call the \"\(method.name.base)\" method."
+
+  let request: String
+  if method.isInputStreaming {
+    request = "A streaming request producing `\(method.inputType)` messages."
+  } else {
+    request = "A request containing a single `\(method.inputType)` message."
+  }
+
+  let parameters = """
+    /// - Parameters:
+    ///   - request: \(request)
+    """
+
+  let serializers = """
+    ///   - serializer: A serializer for `\(method.inputType)` messages.
+    ///   - deserializer: A deserializer for `\(method.outputType)` messages.
+    """
+
+  let otherParameters = """
+    ///   - options: Options to apply to this RPC.
+    ///   - handleResponse: A closure which handles the response, the result of which is
+    ///       returned to the caller. Returning from the closure will cancel the RPC if it
+    ///       hasn't already finished.
+    /// - Returns: The result of `handleResponse`.
+    """
+
+  let allParameters: String
+  if includeSerializers {
+    allParameters = parameters + "\n" + serializers + "\n" + otherParameters
+  } else {
+    allParameters = parameters + "\n" + otherParameters
+  }
+
+  return Docs.interposeDocs(method.documentation, between: summary, and: allParameters)
+}
+
+private func explodedDocs(for method: MethodDescriptor) -> String {
+  let summary = "/// Call the \"\(method.name.base)\" method."
+  var parameters = """
+    /// - Parameters:
+    """
+
+  if !method.isInputStreaming {
+    parameters += "\n"
+    parameters += """
+      ///   - message: request message to send.
+      """
+  }
+
+  parameters += "\n"
+  parameters += """
+    ///   - metadata: Additional metadata to send, defaults to empty.
+    ///   - options: Options to apply to this RPC, defaults to `.defaults`.
+    """
+
+  if method.isInputStreaming {
+    parameters += "\n"
+    parameters += """
+      ///   - producer: A closure producing request messages to send to the server. The request
+      ///       stream is closed when the closure returns.
+      """
+  }
+
+  parameters += "\n"
+  parameters += """
+    ///   - handleResponse: A closure which handles the response, the result of which is
+    ///       returned to the caller. Returning from the closure will cancel the RPC if it
+    ///       hasn't already finished.
+    /// - Returns: The result of `handleResponse`.
+    """
+
+  return Docs.interposeDocs(method.documentation, between: summary, and: parameters)
+}

Sources/GRPCCodeGen/Internal/StructuredSwift+Server.swift

@@ -56,13 +56,31 @@ extension ProtocolDescription {
     name: String,
     methods: [MethodDescriptor]
   ) -> Self {
+    func docs(for method: MethodDescriptor) -> String {
+      let summary = """
+        /// Handle the "\(method.name.normalizedBase)" method.
+        """
+
+      let parameters = """
+        /// - Parameters:
+        ///   - request: A streaming request of `\(method.inputType)` messages.
+        ///   - context: Context providing information about the RPC.
+        /// - Throws: Any error which occurred during the processing of the request. Thrown errors
+        ///     of type `RPCError` are mapped to appropriate statuses. All other errors are converted
+        ///     to an internal error.
+        /// - Returns: A streaming response of `\(method.outputType)` messages.
+        """
+
+      return Docs.interposeDocs(method.documentation, between: summary, and: parameters)
+    }
+
     return ProtocolDescription(
       accessModifier: accessLevel,
       name: name,
       conformances: ["GRPCCore.RegistrableRPCService"],
       members: methods.map { method in
         .commentable(
-          .preFormatted(method.documentation),
+          .preFormatted(docs(for: method)),
           .function(
             signature: .serverMethod(
               name: method.name.generatedLowerCase,
@@ -123,13 +141,45 @@ extension ProtocolDescription {
     streamingProtocol: String,
     methods: [MethodDescriptor]
   ) -> Self {
+    func docs(for method: MethodDescriptor) -> String {
+      let summary = """
+        /// Handle the "\(method.name.normalizedBase)" method.
+        """
+
+      let request: String
+      if method.isInputStreaming {
+        request = "A streaming request of `\(method.inputType)` messages."
+      } else {
+        request = "A request containing a single `\(method.inputType)` message."
+      }
+
+      let returns: String
+      if method.isOutputStreaming {
+        returns = "A streaming response of `\(method.outputType)` messages."
+      } else {
+        returns = "A response containing a single `\(method.outputType)` message."
+      }
+
+      let parameters = """
+        /// - Parameters:
+        ///   - request: \(request)
+        ///   - context: Context providing information about the RPC.
+        /// - Throws: Any error which occurred during the processing of the request. Thrown errors
+        ///     of type `RPCError` are mapped to appropriate statuses. All other errors are converted
+        ///     to an internal error.
+        /// - Returns: \(returns)
+        """
+
+      return Docs.interposeDocs(method.documentation, between: summary, and: parameters)
+    }
+
     return ProtocolDescription(
       accessModifier: accessLevel,
       name: name,
       conformances: [streamingProtocol],
       members: methods.map { method in
         .commentable(
-          .preFormatted(method.documentation),
+          .preFormatted(docs(for: method)),
           .function(
             signature: .serverMethod(
               name: method.name.generatedLowerCase,