From 49531bb04676bc898f27b8cd567a364eca050fe2 Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Thu, 10 Aug 2023 12:45:10 -0700 Subject: [PATCH 1/9] Add error info generation for operations. --- .../amazon/smithy/swift/codegen/ServiceGenerator.kt | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index a9789a471..be8c65d32 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -13,6 +13,7 @@ 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.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 @@ -59,6 +60,14 @@ class ServiceGenerator( writer.writeShapeDocs(op) writer.writeAvailableAttribute(model, op) + if (op.errors.size > 0) writer.writeSingleLineDocs { write("") } + for (error in op.errors) { + val errorIsDocumented = model.getShape(error.toShapeId()).get().hasTrait(DocumentationTrait::class.java) + val errorCause = if (errorIsDocumented) model.getShape(error.toShapeId()).get().getTrait(DocumentationTrait::class.java).get().value else "[no documentation found]" + val errorDoc = " - Throws: `${error.name}` if / when $errorCause" + writer.writeDocs("\t$errorDoc") + } + val accessSpecifier = if (insideProtocol) "" else "public " writer.write( From 5fe7a3427c960223352c715a1efa6e7b911c6114 Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Fri, 11 Aug 2023 15:43:29 -0700 Subject: [PATCH 2/9] wip - committing for investigate source of Throws issue with Josh --- .../smithy/swift/codegen/ServiceGenerator.kt | 48 +++++++++++++++---- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index be8c65d32..fc700f8a7 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -12,10 +12,13 @@ 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.Shape +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.getTrait import software.amazon.smithy.swift.codegen.model.toLowerCamelCase /* @@ -57,16 +60,7 @@ class ServiceGenerator( val outputShape = opIndex.getOutput(op).get() val outputShapeName = symbolProvider.toSymbol(outputShape).name - writer.writeShapeDocs(op) - writer.writeAvailableAttribute(model, op) - - if (op.errors.size > 0) writer.writeSingleLineDocs { write("") } - for (error in op.errors) { - val errorIsDocumented = model.getShape(error.toShapeId()).get().hasTrait(DocumentationTrait::class.java) - val errorCause = if (errorIsDocumented) model.getShape(error.toShapeId()).get().getTrait(DocumentationTrait::class.java).get().value else "[no documentation found]" - val errorDoc = " - Throws: `${error.name}` if / when $errorCause" - writer.writeDocs("\t$errorDoc") - } + renderOperationDoc(model, op, writer) val accessSpecifier = if (insideProtocol) "" else "public " @@ -77,6 +71,40 @@ class ServiceGenerator( outputShapeName ) } + + /** + * Helper method for generating in-line documentation for operation + */ + private fun renderOperationDoc(model: Model, op: OperationShape, writer: SwiftWriter) { + writer.writeShapeDocs(op) + writer.writeAvailableAttribute(model, op) + + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("- Parameter ${op.inputShape.name} : ${retrieveMemberShapeDoc(op.inputShape, model)}") } + + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("- Returns: `${op.outputShape.name}` : ${retrieveMemberShapeDoc(op.outputShape, model)}") } + + if (op.errors.size > 0) { + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("- Throws:") } + for (error in op.errors) { + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write ("- `${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 when { + docTrait == null -> "[no documentation found]" + else -> docTrait.value + } + } } fun render() { From ff27bf08fc3a7508ed14bac001d18c4cd7f4b48c Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Fri, 11 Aug 2023 17:39:35 -0700 Subject: [PATCH 3/9] Add codegen for params, return, and refine exception codegen. --- .../smithy/swift/codegen/ServiceGenerator.kt | 20 +++++++++---------- .../test/kotlin/ContentMd5MiddlewareTests.kt | 10 ++++++++++ .../HttpProtocolClientGeneratorTests.kt | 10 ++++++++++ .../test/kotlin/IdempotencyTokenTraitTests.kt | 10 ++++++++++ .../Isolated/contentmd5checksum.smithy | 1 + .../Isolated/idempotencyToken.smithy | 1 + .../service-generator-test-operations.smithy | 1 + 7 files changed, 43 insertions(+), 10 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index fc700f8a7..6e9ce7455 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -12,7 +12,6 @@ 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.Shape import software.amazon.smithy.model.shapes.ShapeId import software.amazon.smithy.model.shapes.StructureShape import software.amazon.smithy.model.traits.DocumentationTrait @@ -20,6 +19,7 @@ import software.amazon.smithy.model.traits.StreamingTrait import software.amazon.smithy.swift.codegen.integration.ProtocolGenerator import software.amazon.smithy.swift.codegen.model.getTrait import software.amazon.smithy.swift.codegen.model.toLowerCamelCase +import software.amazon.smithy.swift.codegen.model.toUpperCamelCase /* * Generates a Swift protocol for the service @@ -75,7 +75,7 @@ class ServiceGenerator( /** * Helper method for generating in-line documentation for operation */ - private fun renderOperationDoc(model: Model, op: OperationShape, writer: SwiftWriter) { + fun renderOperationDoc(model: Model, op: OperationShape, writer: SwiftWriter) { writer.writeShapeDocs(op) writer.writeAvailableAttribute(model, op) @@ -85,20 +85,20 @@ class ServiceGenerator( writer.writeSingleLineDocs { write("") } writer.writeSingleLineDocs { write("- Returns: `${op.outputShape.name}` : ${retrieveMemberShapeDoc(op.outputShape, model)}") } - if (op.errors.size > 0) { - writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write("- Throws:") } - for (error in op.errors) { - writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write ("- `${error.name}` : ${retrieveMemberShapeDoc(error.toShapeId(), model)}") } - } + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Wrapper object for possible exceptions listed below.") } + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("__Possible Exceptions:__") } + for (error in op.errors) { + writer.writeSingleLineDocs { write("- `${error.name}` : ${retrieveMemberShapeDoc(error.toShapeId(), model)}") } } + if (op.errors.size == 0) writer.writeSingleLineDocs { write("This operation throws no exceptions.") } } /** * Helper method to grab documentation for operation's member shapes (input, output, error(s) */ - private fun retrieveMemberShapeDoc(shapeId : ShapeId, model : Model) : String { + private fun retrieveMemberShapeDoc(shapeId: ShapeId, model: Model): String { val docTrait = model.getShape(shapeId).get().getTrait(DocumentationTrait::class.java).getOrNull() return when { docTrait == null -> "[no documentation found]" diff --git a/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt b/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt index 2ae1751c3..050364ea7 100644 --- a/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt @@ -9,6 +9,16 @@ class ContentMd5MiddlewareTests { val expectedContents = """ extension RestXmlProtocolClient: RestXmlProtocolClientProtocol { + /// This is a very cool operation. + /// + /// - Parameter IdempotencyTokenWithStructureInput : [no documentation found] + /// + /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found] + /// + /// - Throws: `IdempotencyTokenWithStructureError` : Wrapper object for possible exceptions listed below. + /// + /// __Possible Exceptions:__ + /// This operation throws no exceptions. public func idempotencyTokenWithStructure(input: IdempotencyTokenWithStructureInput) async throws -> IdempotencyTokenWithStructureOutputResponse { let context = ClientRuntime.HttpContextBuilder() diff --git a/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt b/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt index 30dd89e8e..d81397eb0 100644 --- a/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt @@ -107,6 +107,16 @@ 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] + /// + /// - Throws: `AllocateWidgetError` : Wrapper object for possible exceptions listed below. + /// + /// __Possible Exceptions:__ + /// This operation throws no exceptions. public func allocateWidget(input: AllocateWidgetInput) async throws -> AllocateWidgetOutputResponse { let context = ClientRuntime.HttpContextBuilder() diff --git a/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt b/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt index 71b602d7b..1ebf9ed5a 100644 --- a/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt @@ -9,6 +9,16 @@ class IdempotencyTokenTraitTests { val expectedContents = """ extension RestXmlProtocolClient: RestXmlProtocolClientProtocol { + /// This is a very cool operation. + /// + /// - Parameter IdempotencyTokenWithStructureInput : [no documentation found] + /// + /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found] + /// + /// - Throws: `IdempotencyTokenWithStructureError` : Wrapper object for possible exceptions listed below. + /// + /// __Possible Exceptions:__ + /// This operation throws no exceptions. public func idempotencyTokenWithStructure(input: IdempotencyTokenWithStructureInput) async throws -> IdempotencyTokenWithStructureOutputResponse { let context = ClientRuntime.HttpContextBuilder() diff --git a/smithy-swift-codegen/src/test/resources/Isolated/contentmd5checksum.smithy b/smithy-swift-codegen/src/test/resources/Isolated/contentmd5checksum.smithy index b74a7c3ff..219d4069b 100644 --- a/smithy-swift-codegen/src/test/resources/Isolated/contentmd5checksum.smithy +++ b/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 { diff --git a/smithy-swift-codegen/src/test/resources/Isolated/idempotencyToken.smithy b/smithy-swift-codegen/src/test/resources/Isolated/idempotencyToken.smithy index 67ac2e16a..eb2c97c26 100644 --- a/smithy-swift-codegen/src/test/resources/Isolated/idempotencyToken.smithy +++ b/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, } diff --git a/smithy-swift-codegen/src/test/resources/service-generator-test-operations.smithy b/smithy-swift-codegen/src/test/resources/service-generator-test-operations.smithy index db924bd8c..b1a74de8a 100644 --- a/smithy-swift-codegen/src/test/resources/service-generator-test-operations.smithy +++ b/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 From 38bbc209ab1fc0e709261a270c993c3fcd5ab27d Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Sun, 13 Aug 2023 00:16:03 -0700 Subject: [PATCH 4/9] Add service errors to operation doc codegen & change formatitng. --- .../smithy/swift/codegen/ServiceGenerator.kt | 22 +++++++++++-------- .../HttpProtocolClientGenerator.kt | 2 +- .../test/kotlin/ContentMd5MiddlewareTests.kt | 2 +- .../HttpProtocolClientGeneratorTests.kt | 2 +- .../test/kotlin/IdempotencyTokenTraitTests.kt | 2 +- 5 files changed, 17 insertions(+), 13 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index 6e9ce7455..f712087d4 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -12,6 +12,7 @@ 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 @@ -44,6 +45,7 @@ class ServiceGenerator( */ fun renderOperationDefinition( model: Model, + service: ServiceShape, symbolProvider: SymbolProvider, writer: SwiftWriter, opIndex: OperationIndex, @@ -60,7 +62,7 @@ class ServiceGenerator( val outputShape = opIndex.getOutput(op).get() val outputShapeName = symbolProvider.toSymbol(outputShape).name - renderOperationDoc(model, op, writer) + renderOperationDoc(model, service, op, writer) val accessSpecifier = if (insideProtocol) "" else "public " @@ -75,24 +77,26 @@ class ServiceGenerator( /** * Helper method for generating in-line documentation for operation */ - fun renderOperationDoc(model: Model, op: OperationShape, writer: SwiftWriter) { + private fun renderOperationDoc(model: Model, service: ServiceShape, op: OperationShape, writer: SwiftWriter) { writer.writeShapeDocs(op) writer.writeAvailableAttribute(model, op) writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write("- Parameter ${op.inputShape.name} : ${retrieveMemberShapeDoc(op.inputShape, model)}") } + writer.writeDocs("\\- Parameter ${op.inputShape.name} : ${retrieveMemberShapeDoc(op.inputShape, model)}") writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write("- Returns: `${op.outputShape.name}` : ${retrieveMemberShapeDoc(op.outputShape, model)}") } + writer.writeDocs("\\- Returns: \\`${op.outputShape.name}\\` : ${retrieveMemberShapeDoc(op.outputShape, model)}") writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Wrapper object for possible exceptions listed below.") } + writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Place-holder wrapper object for possible exceptions listed below.") } writer.writeSingleLineDocs { write("") } writer.writeSingleLineDocs { write("__Possible Exceptions:__") } - for (error in op.errors) { - writer.writeSingleLineDocs { write("- `${error.name}` : ${retrieveMemberShapeDoc(error.toShapeId(), model)}") } + + if (op.getErrors(service).size == 0) writer.writeSingleLineDocs { write("This operation throws no exceptions.") } + + for (error in op.getErrors(service)) { + writer.writeDocs("\\- \\`${error.name}\\` : ${retrieveMemberShapeDoc(error.toShapeId(), model)}") } - if (op.errors.size == 0) writer.writeSingleLineDocs { write("This operation throws no exceptions.") } } /** @@ -155,7 +159,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("}") diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/integration/HttpProtocolClientGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/integration/HttpProtocolClientGenerator.kt index b7719630e..02d720b50 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/integration/HttpProtocolClientGenerator.kt +++ b/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) diff --git a/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt b/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt index 050364ea7..b94422665 100644 --- a/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt @@ -15,7 +15,7 @@ class ContentMd5MiddlewareTests { /// /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found] /// - /// - Throws: `IdempotencyTokenWithStructureError` : Wrapper object for possible exceptions listed below. + /// - Throws: `IdempotencyTokenWithStructureError` : Place-holder wrapper object for possible exceptions listed below. /// /// __Possible Exceptions:__ /// This operation throws no exceptions. diff --git a/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt b/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt index d81397eb0..ad674b9cb 100644 --- a/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt @@ -113,7 +113,7 @@ class HttpProtocolClientGeneratorTests { /// /// - Returns: `AllocateWidgetOutputResponse` : [no documentation found] /// - /// - Throws: `AllocateWidgetError` : Wrapper object for possible exceptions listed below. + /// - Throws: `AllocateWidgetError` : Place-holder wrapper object for possible exceptions listed below. /// /// __Possible Exceptions:__ /// This operation throws no exceptions. diff --git a/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt b/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt index 1ebf9ed5a..64b112ce6 100644 --- a/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt @@ -15,7 +15,7 @@ class IdempotencyTokenTraitTests { /// /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found] /// - /// - Throws: `IdempotencyTokenWithStructureError` : Wrapper object for possible exceptions listed below. + /// - Throws: `IdempotencyTokenWithStructureError` : Place-holder wrapper object for possible exceptions listed below. /// /// __Possible Exceptions:__ /// This operation throws no exceptions. From 8f6db1c1e0f6a130be61b4d6e2c3a25705f31f15 Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Mon, 14 Aug 2023 08:40:14 -0700 Subject: [PATCH 5/9] Fix wrong assumption that all operations have error wrapper object. --- .../amazon/smithy/swift/codegen/ServiceGenerator.kt | 12 ++++++------ .../src/test/kotlin/ContentMd5MiddlewareTests.kt | 5 ----- .../test/kotlin/HttpProtocolClientGeneratorTests.kt | 5 ----- .../src/test/kotlin/IdempotencyTokenTraitTests.kt | 5 ----- 4 files changed, 6 insertions(+), 21 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index f712087d4..b78572574 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -87,12 +87,12 @@ class ServiceGenerator( writer.writeSingleLineDocs { write("") } writer.writeDocs("\\- Returns: \\`${op.outputShape.name}\\` : ${retrieveMemberShapeDoc(op.outputShape, model)}") - writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Place-holder wrapper object for possible exceptions listed below.") } - writer.writeSingleLineDocs { write("") } - writer.writeSingleLineDocs { write("__Possible Exceptions:__") } - - if (op.getErrors(service).size == 0) writer.writeSingleLineDocs { write("This operation throws no exceptions.") } + if (op.getErrors(service).size > 0) { + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Place-holder wrapper object for possible exceptions listed below.") } + writer.writeSingleLineDocs { write("") } + writer.writeSingleLineDocs { write("__Possible Exceptions:__") } + } for (error in op.getErrors(service)) { writer.writeDocs("\\- \\`${error.name}\\` : ${retrieveMemberShapeDoc(error.toShapeId(), model)}") diff --git a/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt b/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt index b94422665..c2c33cab3 100644 --- a/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/ContentMd5MiddlewareTests.kt @@ -14,11 +14,6 @@ class ContentMd5MiddlewareTests { /// - Parameter IdempotencyTokenWithStructureInput : [no documentation found] /// /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found] - /// - /// - Throws: `IdempotencyTokenWithStructureError` : Place-holder wrapper object for possible exceptions listed below. - /// - /// __Possible Exceptions:__ - /// This operation throws no exceptions. public func idempotencyTokenWithStructure(input: IdempotencyTokenWithStructureInput) async throws -> IdempotencyTokenWithStructureOutputResponse { let context = ClientRuntime.HttpContextBuilder() diff --git a/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt b/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt index ad674b9cb..cfc0227d5 100644 --- a/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/HttpProtocolClientGeneratorTests.kt @@ -112,11 +112,6 @@ class HttpProtocolClientGeneratorTests { /// - Parameter AllocateWidgetInput : [no documentation found] /// /// - Returns: `AllocateWidgetOutputResponse` : [no documentation found] - /// - /// - Throws: `AllocateWidgetError` : Place-holder wrapper object for possible exceptions listed below. - /// - /// __Possible Exceptions:__ - /// This operation throws no exceptions. public func allocateWidget(input: AllocateWidgetInput) async throws -> AllocateWidgetOutputResponse { let context = ClientRuntime.HttpContextBuilder() diff --git a/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt b/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt index 64b112ce6..9d5d0cde9 100644 --- a/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt +++ b/smithy-swift-codegen/src/test/kotlin/IdempotencyTokenTraitTests.kt @@ -14,11 +14,6 @@ class IdempotencyTokenTraitTests { /// - Parameter IdempotencyTokenWithStructureInput : [no documentation found] /// /// - Returns: `IdempotencyTokenWithStructureOutputResponse` : [no documentation found] - /// - /// - Throws: `IdempotencyTokenWithStructureError` : Place-holder wrapper object for possible exceptions listed below. - /// - /// __Possible Exceptions:__ - /// This operation throws no exceptions. public func idempotencyTokenWithStructure(input: IdempotencyTokenWithStructureInput) async throws -> IdempotencyTokenWithStructureOutputResponse { let context = ClientRuntime.HttpContextBuilder() From 9998fdd9d8748fcba8f70774c10b38370b2d06d0 Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Mon, 14 Aug 2023 13:22:05 -0700 Subject: [PATCH 6/9] Resolve David's PR comments on kotlin syntax. --- .../smithy/swift/codegen/ServiceGenerator.kt | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index b78572574..2e07d23c2 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -81,16 +81,20 @@ class ServiceGenerator( writer.writeShapeDocs(op) writer.writeAvailableAttribute(model, op) - writer.writeSingleLineDocs { write("") } + fun writeEmptyLine() { + writer.writeSingleLineDocs { write("") } + } + + writeEmptyLine() writer.writeDocs("\\- Parameter ${op.inputShape.name} : ${retrieveMemberShapeDoc(op.inputShape, model)}") - writer.writeSingleLineDocs { write("") } + writeEmptyLine() writer.writeDocs("\\- Returns: \\`${op.outputShape.name}\\` : ${retrieveMemberShapeDoc(op.outputShape, model)}") - if (op.getErrors(service).size > 0) { - writer.writeSingleLineDocs { write("") } + if (op.getErrors(service).isNotEmpty()) { + writeEmptyLine() writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Place-holder wrapper object for possible exceptions listed below.") } - writer.writeSingleLineDocs { write("") } + writeEmptyLine() writer.writeSingleLineDocs { write("__Possible Exceptions:__") } } From 294e230d84577c0159551ef5c8ec3bf2a9577113 Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Mon, 14 Aug 2023 16:11:26 -0700 Subject: [PATCH 7/9] Change error doc formatting. --- .../software/amazon/smithy/swift/codegen/ServiceGenerator.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index 2fa5bf724..6fdb580fa 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -93,7 +93,7 @@ class ServiceGenerator( if (op.getErrors(service).isNotEmpty()) { writeEmptyLine() - writer.writeSingleLineDocs { write("- Throws: `${op.toUpperCamelCase() + "Error"}` : Place-holder wrapper object for possible exceptions listed below.") } + writer.writeSingleLineDocs { write("- Throws: One of the exceptions listed below __Possible Exceptions__.") } writeEmptyLine() writer.writeSingleLineDocs { write("__Possible Exceptions:__") } op.getErrors(service).forEach { error -> From a8e3694d1f45193841a7847038b33ff426710395 Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Mon, 14 Aug 2023 16:26:13 -0700 Subject: [PATCH 8/9] Resolve kt lint issue. --- .../software/amazon/smithy/swift/codegen/ServiceGenerator.kt | 2 -- 1 file changed, 2 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index 6fdb580fa..3d32a439c 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -18,9 +18,7 @@ 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.getTrait import software.amazon.smithy.swift.codegen.model.toLowerCamelCase -import software.amazon.smithy.swift.codegen.model.toUpperCamelCase /* * Generates a Swift protocol for the service From ba192835101d227dde71660f97416c556e3bb59d Mon Sep 17 00:00:00 2001 From: Sichan Yoo Date: Tue, 15 Aug 2023 10:44:17 -0700 Subject: [PATCH 9/9] Kotlin syntax update. --- .../software/amazon/smithy/swift/codegen/ServiceGenerator.kt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt index 3d32a439c..66384add0 100644 --- a/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt +++ b/smithy-swift-codegen/src/main/kotlin/software/amazon/smithy/swift/codegen/ServiceGenerator.kt @@ -105,10 +105,7 @@ class ServiceGenerator( */ private fun retrieveMemberShapeDoc(shapeId: ShapeId, model: Model): String { val docTrait = model.getShape(shapeId).get().getTrait(DocumentationTrait::class.java).getOrNull() - return when { - docTrait == null -> "[no documentation found]" - else -> docTrait.value - } + return docTrait?.value ?: "[no documentation found]" } }