Merge pull request #757 from MYoung25/docs/response-structure

docs: response structure and base service exception
smithy-lang · May 3, 2023 · 59b5ad5 · 59b5ad5
2 parents 7a522f3 + 7208389
commit 59b5ad5
Show file tree

Hide file tree

Showing 5 changed files with 81 additions and 27 deletions.
diff --git a/...escript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CodegenUtils.java b/...escript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CodegenUtils.java
@@ -21,10 +21,12 @@
 import java.util.stream.Collectors;
 import software.amazon.smithy.codegen.core.CodegenException;
 import software.amazon.smithy.codegen.core.Symbol;
+import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.knowledge.EventStreamIndex;
 import software.amazon.smithy.model.shapes.MemberShape;
 import software.amazon.smithy.model.shapes.OperationShape;
+import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.shapes.StructureShape;
 import software.amazon.smithy.model.traits.StreamingTrait;
@@ -237,4 +239,17 @@ static void writeInlineStreamingMemberType(
         writer.writeInline("Omit<$1T, $2S> & { $2L$3L: $1T[$2S]|string|Uint8Array|Buffer }",
                 containerSymbol, memberName, optionalSuffix);
     }
+
+    public static String getServiceName(
+            TypeScriptSettings settings,
+            Model model,
+            SymbolProvider symbolProvider
+    ) {
+        ServiceShape service = settings.getService(model);
+        return symbolProvider.toSymbol(service).getName().replaceAll("(Client)$", "");
+    }
+
+    public static String getServiceExceptionName(String serviceName) {
+        return serviceName + "ServiceException";
+    }
 }
diff --git a/...ipt-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java b/...ipt-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java
@@ -177,10 +177,13 @@ private String getCommandExample(String serviceName, String configName, String c
                 + String.format("const client = new %s(config);%n", serviceName)
                 + String.format("const input = %s%n",
                         StructureExampleGenerator.generateStructuralHintDocumentation(
-                                model.getShape(operation.getInputShape()).get(), model))
+                                model.getShape(operation.getInputShape()).get(), model, false))
                 + String.format("const command = new %s(input);%n", commandName)
                 + "const response = await client.send(command);\n"
-                + "```\n"
+                + String.format("%s%n",
+                        StructureExampleGenerator.generateStructuralHintDocumentation(
+                                model.getShape(operation.getOutputShape()).get(), model, true))
+                + "\n```\n"
                 + "\n"
                 + String.format("@param %s - {@link %s}%n", commandInput, commandInput)
                 + String.format("@returns {@link %s}%n", commandOutput)
@@ -206,6 +209,11 @@ private String getThrownExceptions() {
             }
             buffer.append("\n\n");
         }
+
+        String name = CodegenUtils.getServiceName(settings, model, symbolProvider);
+        buffer.append(String.format("@throws {@link %s}%n", CodegenUtils.getServiceExceptionName(name)));
+        buffer.append(String.format("<p>Base exception class for all service exceptions from %s service.</p>%n", name));
+
         return buffer.toString();
     }
 

diff --git a/...va/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java b/...va/software/amazon/smithy/typescript/codegen/documentation/StructureExampleGenerator.java
@@ -44,7 +44,7 @@ public abstract class StructureExampleGenerator {
      * };
      * ```
      */
-    public static String generateStructuralHintDocumentation(Shape shape, Model model) {
+    public static String generateStructuralHintDocumentation(Shape shape, Model model, boolean isComment) {
         StringBuilder buffer = new StringBuilder();
         shape(shape, buffer, model, 0, new ShapeTracker());
 
@@ -56,9 +56,9 @@ public static String generateStructuralHintDocumentation(Shape shape, Model mode
                         "([\\w\\\",:\\[\\{] )\\s+",
                         "$1")
                         .replaceAll("\\s+$", ""))
-                .collect(Collectors.joining("\n"));
+                .collect(Collectors.joining((isComment) ? "\n// " : "\n"));
 
-        return s.replaceAll(",$", ";");
+        return ((isComment) ? "// " : "") + s.replaceAll(",$", ";");
     }
 
     private static void structure(StructureShape structureShape,

diff --git a/...a/software/amazon/smithy/typescript/codegen/integration/AddBaseServiceExceptionClass.java b/...a/software/amazon/smithy/typescript/codegen/integration/AddBaseServiceExceptionClass.java
@@ -22,7 +22,6 @@
 import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.codegen.core.SymbolReference;
 import software.amazon.smithy.model.Model;
-import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.model.traits.ErrorTrait;
 import software.amazon.smithy.typescript.codegen.CodegenUtils;
 import software.amazon.smithy.typescript.codegen.TypeScriptCodegenContext;
@@ -59,8 +58,8 @@ private void writeAdditionalFiles(
     ) {
         boolean isClientSdk = settings.generateClient();
         if (isClientSdk) {
-            String serviceName = getServiceName(settings, model, symbolProvider);
-            String serviceExceptionName = getServiceExceptionName(serviceName);
+            String serviceName = CodegenUtils.getServiceName(settings, model, symbolProvider);
+            String serviceExceptionName = CodegenUtils.getServiceExceptionName(serviceName);
             writerFactory.accept(
                     Paths.get(CodegenUtils.SOURCE_FOLDER, "models", serviceExceptionName + ".ts").toString(),
                     writer -> {
@@ -89,8 +88,8 @@ private void writeAdditionalExports(
     ) {
         boolean isClientSdk = settings.generateClient();
         if (isClientSdk) {
-            String serviceName = getServiceName(settings, model, symbolProvider);
-            String serviceExceptionName = getServiceExceptionName(serviceName);
+            String serviceName = CodegenUtils.getServiceName(settings, model, symbolProvider);
+            String serviceExceptionName = CodegenUtils.getServiceExceptionName(serviceName);
             writer.write("export { $1L } from \"./models/$1L\";", serviceExceptionName);
         }
     }
@@ -110,11 +109,11 @@ public SymbolProvider decorateSymbolProvider(
         return shape -> {
             Symbol symbol = symbolProvider.toSymbol(shape);
             if (shape.hasTrait(ErrorTrait.class)) {
-                String serviceName = getServiceName(settings, model, symbolProvider);
+                String serviceName = CodegenUtils.getServiceName(settings, model, symbolProvider);
                 String baseExceptionAlias = "__BaseException";
                 SymbolReference reference;
                 if (settings.generateClient()) {
-                    String serviceExceptionName = getServiceExceptionName(serviceName);
+                    String serviceExceptionName = CodegenUtils.getServiceExceptionName(serviceName);
                     String namespace = Paths.get(".", "src", "models", serviceExceptionName).toString();
                     Symbol serviceExceptionSymbol = Symbol.builder()
                             .name(serviceExceptionName)
@@ -138,16 +137,4 @@ public SymbolProvider decorateSymbolProvider(
         };
     }
 
-    private String getServiceName(
-        TypeScriptSettings settings,
-        Model model,
-        SymbolProvider symbolProvider
-    ) {
-        ServiceShape service = settings.getService(model);
-        return symbolProvider.toSymbol(service).getName().replaceAll("(Client)$", "");
-    }
-
-    private String getServiceExceptionName(String serviceName) {
-        return serviceName + "ServiceException";
-    }
 }
diff --git a/...oftware/amazon/smithy/typescript/codegen/documentation/StructureExampleGeneratorTest.java b/...oftware/amazon/smithy/typescript/codegen/documentation/StructureExampleGeneratorTest.java
@@ -94,7 +94,7 @@ public class StructureExampleGeneratorTest {
     @Test
     public void generatesStructuralHintDocumentation_map() {
         assertThat(
-                StructureExampleGenerator.generateStructuralHintDocumentation(map, model),
+                StructureExampleGenerator.generateStructuralHintDocumentation(map, model, false),
                 equalTo("""
                         { // map
                           "<keys>": "STRING_VALUE",
@@ -104,7 +104,7 @@ public void generatesStructuralHintDocumentation_map() {
     @Test
     public void generatesStructuralHintDocumentation_structure() {
         assertThat(
-                StructureExampleGenerator.generateStructuralHintDocumentation(structure, model),
+                StructureExampleGenerator.generateStructuralHintDocumentation(structure, model, false),
                 equalTo("""
                         { // structure
                           string: "STRING_VALUE",
@@ -144,11 +144,55 @@ public void generatesStructuralHintDocumentation_structure() {
                           },
                         };"""));
     }
+
+    @Test
+    public void generatesStructuralHintDocumentation_structure_asComment() {
+        assertThat(
+                StructureExampleGenerator.generateStructuralHintDocumentation(structure, model, true),
+                equalTo("""
+                        // { // structure
+                        //   string: "STRING_VALUE",
+                        //   list: [ // list
+                        //     "STRING_VALUE",
+                        //   ],
+                        //   map: { // map
+                        //     "<keys>": "STRING_VALUE",
+                        //   },
+                        //   list2: [
+                        //     "STRING_VALUE",
+                        //   ],
+                        //   list3: [
+                        //     "STRING_VALUE",
+                        //   ],
+                        //   list4: [
+                        //     "STRING_VALUE",
+                        //   ],
+                        //   list5: [
+                        //     "STRING_VALUE",
+                        //   ],
+                        //   list6: "<list>",
+                        //   list7: "<list>",
+                        //   structure: {
+                        //     string: "STRING_VALUE",
+                        //     list: "<list>",
+                        //     map: {
+                        //       "<keys>": "STRING_VALUE",
+                        //     },
+                        //     list2: "<list>",
+                        //     list3: "<list>",
+                        //     list4: "<list>",
+                        //     list5: "<list>",
+                        //     list6: "<list>",
+                        //     list7: "<list>",
+                        //     structure: "<structure>",
+                        //   },
+                        // };"""));
+    }
 
     @Test
     public void generatesStructuralHintDocumentation_list() {
         assertThat(
-                StructureExampleGenerator.generateStructuralHintDocumentation(list, model),
+                StructureExampleGenerator.generateStructuralHintDocumentation(list, model, false),
                 equalTo("""
                         [ // list
                           "STRING_VALUE",