fix: Add documentation generation for operations. (#578)

* Add error info generation for operations.

---------

Co-authored-by: Sichan Yoo <[email protected]>

Author: sichanyoo

smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt

@@ -12,7 +12,10 @@ import software.amazon.smithy.model.Model
 import software.amazon.smithy.model.knowledge.OperationIndex
 import software.amazon.smithy.model.knowledge.TopDownIndex
 import software.amazon.smithy.model.shapes.OperationShape
+import software.amazon.smithy.model.shapes.ServiceShape
+import software.amazon.smithy.model.shapes.ShapeId
 import software.amazon.smithy.model.shapes.StructureShape
+import software.amazon.smithy.model.traits.DocumentationTrait
 import software.amazon.smithy.model.traits.StreamingTrait
 import software.amazon.smithy.swift.codegen.integration.ProtocolGenerator
 import software.amazon.smithy.swift.codegen.model.toLowerCamelCase
@@ -40,6 +43,7 @@ class ServiceGenerator(
          */
         fun renderOperationDefinition(
             model: Model,
+            service: ServiceShape,
             symbolProvider: SymbolProvider,
             writer: SwiftWriter,
             opIndex: OperationIndex,
@@ -56,8 +60,7 @@ class ServiceGenerator(
             val outputShape = opIndex.getOutput(op).get()
             val outputShapeName = symbolProvider.toSymbol(outputShape).name
 
-            writer.writeShapeDocs(op)
-            writer.writeAvailableAttribute(model, op)
+            renderOperationDoc(model, service, op, writer)
 
             val accessSpecifier = if (insideProtocol) "" else "public "
 
@@ -68,6 +71,42 @@ class ServiceGenerator(
                 outputShapeName
             )
         }
+
+        /**
+         * Helper method for generating in-line documentation for operation
+         */
+        private fun renderOperationDoc(model: Model, service: ServiceShape, op: OperationShape, writer: SwiftWriter) {
+            writer.writeShapeDocs(op)
+            writer.writeAvailableAttribute(model, op)
+
+            fun writeEmptyLine() {
+                writer.writeSingleLineDocs { write("") }
+            }
+
+            writeEmptyLine()
+            writer.writeDocs("\\- Parameter ${op.inputShape.name} : ${retrieveMemberShapeDoc(op.inputShape, model)}")
+
+            writeEmptyLine()
+            writer.writeDocs("\\- Returns: \\`${op.outputShape.name}\\` : ${retrieveMemberShapeDoc(op.outputShape, model)}")
+
+            if (op.getErrors(service).isNotEmpty()) {
+                writeEmptyLine()
+                writer.writeSingleLineDocs { write("- Throws: One of the exceptions listed below __Possible Exceptions__.") }
+                writeEmptyLine()
+                writer.writeSingleLineDocs { write("__Possible Exceptions:__") }
+                op.getErrors(service).forEach { error ->
+                    writer.writeDocs("\\- \\`${error.name}\\` : ${retrieveMemberShapeDoc(error.toShapeId(), model)}")
+                }
+            }
+        }
+
+        /**
+         * Helper method to grab documentation for operation's member shapes (input, output, error(s)
+         */
+        private fun retrieveMemberShapeDoc(shapeId: ShapeId, model: Model): String {
+            val docTrait = model.getShape(shapeId).get().getTrait(DocumentationTrait::class.java).getOrNull()
+            return docTrait?.value ?: "[no documentation found]"
+        }
     }
 
     fun render() {
@@ -118,7 +157,7 @@ class ServiceGenerator(
         writer.openBlock("public protocol ${serviceSymbol.name}Protocol {")
             .call {
                 operations.forEach { op ->
-                    renderOperationDefinition(model, symbolProvider, writer, operationsIndex, op, true)
+                    renderOperationDefinition(model, service, symbolProvider, writer, operationsIndex, op, true)
                 }
             }
             .closeBlock("}")

smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/integration/HttpProtocolClientGenerator.kt

@@ -50,7 +50,7 @@ open class HttpProtocolClientGenerator(
 
         writer.openBlock("extension ${serviceSymbol.name}: ${serviceSymbol.name}Protocol {", "}") {
             operations.forEach {
-                ServiceGenerator.renderOperationDefinition(model, symbolProvider, writer, operationsIndex, it)
+                ServiceGenerator.renderOperationDefinition(model, serviceShape, symbolProvider, writer, operationsIndex, it)
                 writer.openBlock("{", "}") {
                     val operationStackName = "operation"
                     val generator = MiddlewareExecutionGenerator(ctx, writer, httpBindingResolver, httpProtocolCustomizable, operationMiddleware, operationStackName)

smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt

@@ -9,6 +9,11 @@ class ContentMd5MiddlewareTests {
         val expectedContents =
             """
             extension RestXmlProtocolClient: RestXmlProtocolClientProtocol {
+                /// This is a very cool operation.
+                ///
+                /// - Parameter IdempotencyTokenWithStructureInput : [no documentation found]
+                ///
+                /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found]
                 public func idempotencyTokenWithStructure(input: IdempotencyTokenWithStructureInput) async throws -> IdempotencyTokenWithStructureOutputResponse
                 {
                     let context = ClientRuntime.HttpContextBuilder()

smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt

@@ -107,6 +107,11 @@ class HttpProtocolClientGeneratorTests {
         contents.shouldSyntacticSanityCheck()
         val expected = """
         extension RestJsonProtocolClient: RestJsonProtocolClientProtocol {
+            /// This is a very cool operation.
+            ///
+            /// - Parameter AllocateWidgetInput : [no documentation found]
+            ///
+            /// - Returns: `AllocateWidgetOutputResponse` : [no documentation found]
             public func allocateWidget(input: AllocateWidgetInput) async throws -> AllocateWidgetOutputResponse
             {
                 let context = ClientRuntime.HttpContextBuilder()

smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt

@@ -9,6 +9,11 @@ class IdempotencyTokenTraitTests {
         val expectedContents =
             """
             extension RestXmlProtocolClient: RestXmlProtocolClientProtocol {
+                /// This is a very cool operation.
+                ///
+                /// - Parameter IdempotencyTokenWithStructureInput : [no documentation found]
+                ///
+                /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found]
                 public func idempotencyTokenWithStructure(input: IdempotencyTokenWithStructureInput) async throws -> IdempotencyTokenWithStructureOutputResponse
                 {
                     let context = ClientRuntime.HttpContextBuilder()

smithy-swift-codegen/src/test/resources/Isolated/contentmd5checksum.smithy

@@ -15,6 +15,7 @@ service RestXml {
     ]
 }
 
+@documentation("This is a very cool operation.")
 @httpChecksumRequired
 @http(uri: "/IdempotencyTokenWithStructure", method: "PUT")
 operation IdempotencyTokenWithStructure {

smithy-swift-codegen/src/test/resources/Isolated/idempotencyToken.smithy

@@ -16,6 +16,7 @@ service RestXml {
 }
 
 @http(uri: "/IdempotencyTokenWithStructure", method: "PUT")
+@documentation("This is a very cool operation.")
 operation IdempotencyTokenWithStructure {
     input: IdempotencyToken,
 }

smithy-swift-codegen/src/test/resources/service-generator-test-operations.smithy

@@ -80,6 +80,7 @@ operation GetFooStreamingInputNoOutput {
 }
 
 // https://awslabs.github.io/smithy/1.0/spec/core/behavior-traits.html#idempotencytoken-trait
+@documentation("This is a very cool operation.")
 @http(method: "POST", uri: "/input/AllocateWidget")
 operation AllocateWidget {
     input: AllocateWidgetInput