misc: pr feedback

Author: 0marperez

codegen/aws-sdk-codegen/src/main/kotlin/aws/sdk/kotlin/codegen/ModuleDocumentationIntegration.kt

@@ -9,11 +9,12 @@ import software.amazon.smithy.kotlin.codegen.model.getTrait
 import software.amazon.smithy.model.Model
 import software.amazon.smithy.model.shapes.ServiceShape
 import software.amazon.smithy.model.traits.TitleTrait
+import java.io.IOException
 
 /**
- * Maps a services SKD ID to its code examples
+ * Maps a service's SDK ID to its code examples
  */
-private val currentCodeExamplesServices = mapOf(
+private val CODE_EXAMPLES_SERVICES_MAP = mapOf(
     "API Gateway" to "https://docs.aws.amazon.com/code-library/latest/ug/kotlin_1_api-gateway_code_examples.html",
     "Auto Scaling" to "https://docs.aws.amazon.com/code-library/latest/ug/kotlin_1_auto-scaling_code_examples.html",
     "Bedrock" to "https://docs.aws.amazon.com/code-library/latest/ug/kotlin_1_bedrock_code_examples.html",
@@ -38,10 +39,10 @@ private val currentCodeExamplesServices = mapOf(
 )
 
 /**
- * Maps a services SKD ID to its handwritten module documentation file in the `resources` dir.
+ * Maps a service's SDK ID to its handwritten module documentation file in the `resources` dir.
  * The module documentation files MUST be markdown files.
  */
-private val currentHandWrittenServices = mapOf(
+private val HAND_WRITTEN_SERVICES_MAP = mapOf(
     "S3" to "S3.md",
 )
 
@@ -55,8 +56,8 @@ private val currentHandWrittenServices = mapOf(
  * See: https://github.com/awslabs/aws-sdk-kotlin/blob/0581f5c5eeaa14dcd8af4ea0dfc088b1057f5ba5/build.gradle.kts#L68-L75
  */
 class ModuleDocumentationIntegration(
-    private val codeExamples: Map<String, String> = currentCodeExamplesServices,
-    private val handWritten: Map<String, String> = currentHandWrittenServices,
+    private val codeExamples: Map<String, String> = CODE_EXAMPLES_SERVICES_MAP,
+    private val handWritten: Map<String, String> = HAND_WRITTEN_SERVICES_MAP,
 ) : KotlinIntegration {
     override fun enabledForService(model: Model, settings: KotlinSettings): Boolean =
         model.expectShape<ServiceShape>(settings.service).sdkId.let {
@@ -77,21 +78,21 @@ class ModuleDocumentationIntegration(
         append(
             generateBoilerPlate(ctx),
         )
-        if (codeExamples.keys.contains(sdkId)) {
+        if (handWritten.keys.contains(sdkId)) {
             append(
-                generateCodeExamplesDocs(sdkId),
+                generateHandWrittenDocs(sdkId),
             )
             appendLine()
         }
-        if (handWritten.keys.contains(sdkId)) {
+        if (codeExamples.keys.contains(sdkId)) {
             append(
-                generateHandWrittenDocs(sdkId),
+                generateCodeExamplesDocs(ctx),
             )
         }
     }
 
     private fun generateBoilerPlate(ctx: CodegenContext) = buildString {
-        // Title must me "Module" followed by the exact module name or dokka won't render it
+        // Title must be "Module" followed by the exact module name or dokka won't render it
         appendLine("# Module ${ctx.settings.pkg.name.split(".").last()}")
         appendLine()
         ctx
@@ -105,9 +106,18 @@ class ModuleDocumentationIntegration(
             }
     }
 
-    private fun generateCodeExamplesDocs(sdkId: String) = buildString {
+    private fun generateCodeExamplesDocs(ctx: CodegenContext) = buildString {
+        val sdkId = ctx.settings.sdkId
+        val codeExampleLink = codeExamples[sdkId]
+        val title = ctx
+            .model
+            .expectShape<ServiceShape>(ctx.settings.service)
+            .getTrait<TitleTrait>()
+            ?.value
+
         appendLine("## Code Examples")
-        appendLine("To see full code examples, see the $sdkId examples in the AWS Code Library. See ${codeExamples[sdkId]}")
+        append("To see full code examples, see the ${title ?: sdkId} examples in the AWS code example library. ")
+        appendLine("See $codeExampleLink")
         appendLine()
     }
 
@@ -117,5 +127,5 @@ class ModuleDocumentationIntegration(
         .getResourceAsStream("aws/sdk/kotlin/codegen/moduledocumentation/${handWritten[sdkId]}")
         ?.bufferedReader()
         ?.readText()
-        ?: throw Exception("Unable to read from file ${handWritten[sdkId]}")
+        ?: throw IOException("Unable to read from file ${handWritten[sdkId]}")
 }

codegen/aws-sdk-codegen/src/test/kotlin/aws/sdk/kotlin/codegen/ModuleDocumentationIntegrationTest.kt

@@ -16,7 +16,7 @@ private val model = """
          use aws.api#service
      
          @service(sdkId: "Test")
-         @title("A test service")
+         @title("Test Service")
          service Test {
              version: "1.0.0",
              operations: []
@@ -60,7 +60,7 @@ class ModuleDocumentationIntegrationTest {
                 """
                     # Module test
                     
-                    A test service
+                    Test Service
                 """.trimIndent(),
             )
 
@@ -76,7 +76,7 @@ class ModuleDocumentationIntegrationTest {
             .shouldContainOnlyOnceWithDiff(
                 """
                     ## Code Examples
-                    To see full code examples, see the Test examples in the AWS Code Library. See https://example.com
+                    To see full code examples, see the Test Service examples in the AWS code example library. See https://example.com
                 """.trimIndent(),
             )
 
@@ -88,7 +88,7 @@ class ModuleDocumentationIntegrationTest {
             .generateModuleDocumentation(
                 ctx.toGenerationContext(),
                 "Test",
-            ).replace("\r\n", "\n")  // Handle CRLF on Windows
+            ).replace("\r\n", "\n") // Handle CRLF on Windows
             .shouldContainOnlyOnceWithDiff(
                 """
                     ## Subtitle