fix: move paginator doc comments to methods (#509)

Author: ganeshnj

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

@@ -107,7 +107,8 @@ class PaginatorGenerator : SwiftIntegration {
         val markerLiteral = paginationInfo.inputTokenMember.toLowerCamelCase()
         val markerLiteralShape = model.expectShape(paginationInfo.inputTokenMember.target)
         val markerLiteralSymbol = symbolProvider.toSymbol(markerLiteralShape)
-        val docBody = """
+        writer.openBlock("extension \$L {", "}", serviceSymbol.name) {
+            val docBody = """
             Paginate over `[${outputSymbol.name}]` results.
             
             When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
@@ -116,13 +117,10 @@ class PaginatorGenerator : SwiftIntegration {
             - Parameters: 
                 - input: A `[${inputSymbol.name}]` to start pagination
             - Returns: An `AsyncSequence` that can iterate over `${outputSymbol.name}`
-        """.trimIndent()
-        writer.write("")
-        writer.writeSingleLineDocs {
-            this.write(docBody)
-        }
-
-        writer.openBlock("extension \$L {", "}", serviceSymbol.name) {
+            """.trimIndent()
+            writer.writeSingleLineDocs {
+                this.write(docBody)
+            }
             writer.openBlock(
                 "public func \$LPaginated(input: \$N) -> \$N<\$N, \$N> {", "}",
                 operationShape.toLowerCamelCase(),
@@ -183,17 +181,16 @@ class PaginatorGenerator : SwiftIntegration {
     ) {
         writer.write("")
         val itemSymbolShape = itemDesc.itemSymbol.getProperty("shape").getOrNull() as? Shape
-        val docBody = """
+
+        writer.openBlock("extension PaginatorSequence where Input == \$N, Output == \$N {", "}", inputSymbol, outputSymbol) {
+            val docBody = """
         This paginator transforms the `AsyncSequence` returned by `${operationShape.toLowerCamelCase()}Paginated`
         to access the nested member `${itemDesc.collectionLiteral}`
         - Returns: `${itemDesc.collectionLiteral}`
-        """.trimIndent()
-
-        writer.writeSingleLineDocs {
-            this.write(docBody)
-        }
-
-        writer.openBlock("extension PaginatorSequence where Input == \$N, Output == \$N {", "}", inputSymbol, outputSymbol) {
+            """.trimIndent()
+            writer.writeSingleLineDocs {
+                this.write(docBody)
+            }
             writer.openBlock("public func \$L() async throws -> \$L {", "}", itemDesc.itemLiteral, itemDesc.collectionLiteral) {
                 if (itemSymbolShape?.isListShape == true) {
                     writer.write("return try await self.asyncCompactMap { item in item.\$L }", itemDesc.itemPathLiteral)

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

@@ -15,29 +15,29 @@ class PaginatorGeneratorTest {
         val context = setupTests("pagination.smithy", "com.test#Lambda")
         val contents = getFileContents(context.manifest, "/Test/Paginators.swift")
         val expected = """
-       /// Paginate over `[ListFunctions2OutputResponse]` results.
-       ///
-       /// When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
-       /// calls are made until the sequence is iterated over. This also means there is no guarantee that the request is valid
-       /// until then. If there are errors in your request, you will see the failures only after you start iterating.
-       /// - Parameters:
-       ///     - input: A `[ListFunctions2Input]` to start pagination
-       /// - Returns: An `AsyncSequence` that can iterate over `ListFunctions2OutputResponse`
-       extension TestClient {
-           public func listFunctions2Paginated(input: ListFunctions2Input) -> ClientRuntime.PaginatorSequence<ListFunctions2Input, ListFunctions2OutputResponse> {
-               return ClientRuntime.PaginatorSequence<ListFunctions2Input, ListFunctions2OutputResponse>(input: input, inputKey: \ListFunctions2Input.marker, outputKey: \ListFunctions2OutputResponse.nextMarker, paginationFunction: self.listFunctions2(input:))
-           }
-       }
+        extension TestClient {
+            /// Paginate over `[ListFunctionsOutputResponse]` results.
+            ///
+            /// When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
+            /// calls are made until the sequence is iterated over. This also means there is no guarantee that the request is valid
+            /// until then. If there are errors in your request, you will see the failures only after you start iterating.
+            /// - Parameters:
+            ///     - input: A `[ListFunctionsInput]` to start pagination
+            /// - Returns: An `AsyncSequence` that can iterate over `ListFunctionsOutputResponse`
+            public func listFunctionsPaginated(input: ListFunctionsInput) -> ClientRuntime.PaginatorSequence<ListFunctionsInput, ListFunctionsOutputResponse> {
+                return ClientRuntime.PaginatorSequence<ListFunctionsInput, ListFunctionsOutputResponse>(input: input, inputKey: \ListFunctionsInput.marker, outputKey: \ListFunctionsOutputResponse.nextMarker, paginationFunction: self.listFunctions(input:))
+            }
+        }
 
-       extension ListFunctions2Input: ClientRuntime.PaginateToken {
-           public func usingPaginationToken(_ token: Swift.String) -> ListFunctions2Input {
-               return ListFunctions2Input(
-                   functionVersion: self.functionVersion,
-                   marker: token,
-                   masterRegion: self.masterRegion,
-                   maxItems: self.maxItems
-               )}
-       }
+        extension ListFunctionsInput: ClientRuntime.PaginateToken {
+            public func usingPaginationToken(_ token: Swift.String) -> ListFunctionsInput {
+                return ListFunctionsInput(
+                    functionVersion: self.functionVersion,
+                    marker: token,
+                    masterRegion: self.masterRegion,
+                    maxItems: self.maxItems
+                )}
+        }
         """.trimIndent()
 
         contents.shouldContainOnlyOnce(expected)
@@ -48,15 +48,15 @@ class PaginatorGeneratorTest {
         val context = setupTests("pagination.smithy", "com.test#Lambda")
         val contents = getFileContents(context.manifest, "/Test/Paginators.swift")
         val expectedCode = """
-        /// Paginate over `[ListFunctionsOutputResponse]` results.
-        ///
-        /// When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
-        /// calls are made until the sequence is iterated over. This also means there is no guarantee that the request is valid
-        /// until then. If there are errors in your request, you will see the failures only after you start iterating.
-        /// - Parameters:
-        ///     - input: A `[ListFunctionsInput]` to start pagination
-        /// - Returns: An `AsyncSequence` that can iterate over `ListFunctionsOutputResponse`
         extension TestClient {
+            /// Paginate over `[ListFunctionsOutputResponse]` results.
+            ///
+            /// When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
+            /// calls are made until the sequence is iterated over. This also means there is no guarantee that the request is valid
+            /// until then. If there are errors in your request, you will see the failures only after you start iterating.
+            /// - Parameters:
+            ///     - input: A `[ListFunctionsInput]` to start pagination
+            /// - Returns: An `AsyncSequence` that can iterate over `ListFunctionsOutputResponse`
             public func listFunctionsPaginated(input: ListFunctionsInput) -> ClientRuntime.PaginatorSequence<ListFunctionsInput, ListFunctionsOutputResponse> {
                 return ClientRuntime.PaginatorSequence<ListFunctionsInput, ListFunctionsOutputResponse>(input: input, inputKey: \ListFunctionsInput.marker, outputKey: \ListFunctionsOutputResponse.nextMarker, paginationFunction: self.listFunctions(input:))
             }
@@ -72,10 +72,10 @@ class PaginatorGeneratorTest {
                 )}
         }
         
-        /// This paginator transforms the `AsyncSequence` returned by `listFunctionsPaginated`
-        /// to access the nested member `[TestClientTypes.FunctionConfiguration]`
-        /// - Returns: `[TestClientTypes.FunctionConfiguration]`
         extension PaginatorSequence where Input == ListFunctionsInput, Output == ListFunctionsOutputResponse {
+            /// This paginator transforms the `AsyncSequence` returned by `listFunctionsPaginated`
+            /// to access the nested member `[TestClientTypes.FunctionConfiguration]`
+            /// - Returns: `[TestClientTypes.FunctionConfiguration]`
             public func functions() async throws -> [TestClientTypes.FunctionConfiguration] {
                 return try await self.asyncCompactMap { item in item.functions }
             }
@@ -90,15 +90,15 @@ class PaginatorGeneratorTest {
         val context = setupTests("pagination-map.smithy", "com.test#TestService")
         val contents = getFileContents(context.manifest, "/Test/Paginators.swift")
         val expectedCode = """
-        /// Paginate over `[PaginatedMapOutputResponse]` results.
-        ///
-        /// When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
-        /// calls are made until the sequence is iterated over. This also means there is no guarantee that the request is valid
-        /// until then. If there are errors in your request, you will see the failures only after you start iterating.
-        /// - Parameters:
-        ///     - input: A `[PaginatedMapInput]` to start pagination
-        /// - Returns: An `AsyncSequence` that can iterate over `PaginatedMapOutputResponse`
         extension TestClient {
+            /// Paginate over `[PaginatedMapOutputResponse]` results.
+            ///
+            /// When this operation is called, an `AsyncSequence` is created. AsyncSequences are lazy so no service
+            /// calls are made until the sequence is iterated over. This also means there is no guarantee that the request is valid
+            /// until then. If there are errors in your request, you will see the failures only after you start iterating.
+            /// - Parameters:
+            ///     - input: A `[PaginatedMapInput]` to start pagination
+            /// - Returns: An `AsyncSequence` that can iterate over `PaginatedMapOutputResponse`
             public func paginatedMapPaginated(input: PaginatedMapInput) -> ClientRuntime.PaginatorSequence<PaginatedMapInput, PaginatedMapOutputResponse> {
                 return ClientRuntime.PaginatorSequence<PaginatedMapInput, PaginatedMapOutputResponse>(input: input, inputKey: \PaginatedMapInput.nextToken, outputKey: \PaginatedMapOutputResponse.inner?.token, paginationFunction: self.paginatedMap(input:))
             }
@@ -112,10 +112,10 @@ class PaginatorGeneratorTest {
                 )}
         }
         
-        /// This paginator transforms the `AsyncSequence` returned by `paginatedMapPaginated`
-        /// to access the nested member `[(String, Swift.Int)]`
-        /// - Returns: `[(String, Swift.Int)]`
         extension PaginatorSequence where Input == PaginatedMapInput, Output == PaginatedMapOutputResponse {
+            /// This paginator transforms the `AsyncSequence` returned by `paginatedMapPaginated`
+            /// to access the nested member `[(String, Swift.Int)]`
+            /// - Returns: `[(String, Swift.Int)]`
             public func mapItems() async throws -> [(String, Swift.Int)] {
                 return try await self.asyncCompactMap { item in item.inner?.mapItems?.map { (${'$'}0, ${'$'}1) } }
             }