Generate examples for API call with bare-bones client and command (#325)

* mark filterSensitiveLog as internal

* generate example for using bare-bone client and command API

also makes filterSensitive internal

* fix typo

Author: AllanZhengYP

smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java

@@ -107,7 +107,8 @@ private void generateClientCommand() {
         writer.addImport("MiddlewareStack", "MiddlewareStack", "@aws-sdk/types");
 
         String name = symbol.getName();
-        writer.writeShapeDocs(operation);
+        writer.writeShapeDocs(operation, shapeDoc -> shapeDoc + "\n" + getCommandExample(serviceSymbol.getName(),
+                configType, name, inputType.getName(), outputType.getName()));
         writer.openBlock("export class $L extends $$Command<$T, $T, $L> {", "}", name, inputType, outputType,
                 configType, () -> {
 
@@ -130,6 +131,26 @@ private void generateClientCommand() {
         });
     }
 
+    private String getCommandExample(String serviceName, String configName, String commandName, String commandInput,
+                    String commandOutput) {
+        String packageName = settings.getPackageName();
+        return "@example\n"
+            + "Use a bare-bones client and the command you need to make an API call.\n"
+            + "```javascript\n"
+            + String.format("import { %s, %s } from \"%s\"; // ES Modules import%n", serviceName, commandName,
+                    packageName)
+            + String.format("// const { %s, %s } = require(\"%s\"); // CommonJS import%n", serviceName, commandName,
+                    packageName)
+            + String.format("const client = new %s(config);%n", serviceName)
+            + String.format("const command = new %s(input);%n", commandName)
+            + "const response = await client.send(command);\n"
+            + "```\n"
+            + "\n"
+            + String.format("@see {@link %s} for command's `input` shape.%n", commandInput)
+            + String.format("@see {@link %s} for command's `response` shape.%n", commandOutput)
+            + String.format("@see {@link %s | config} for command's `input` shape.%n", configName);
+    }
+
     private void generateCommandConstructor() {
         writer.openBlock("constructor(readonly input: $T) {", "}", inputType, () -> {
             // The constructor can be intercepted and changed.

smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/StructureGenerator.java

@@ -199,6 +199,7 @@ private void renderStructureNamespace(StructuredMemberWriter structuredMemberWri
         Symbol symbol = symbolProvider.toSymbol(shape);
         writer.openBlock("export namespace $L {", "}", symbol.getName(), () -> {
             String objectParam = "obj";
+            writer.writeDocs("@internal");
             writer.openBlock("export const filterSensitiveLog = ($L: $L): any => ({", "})",
                 objectParam, symbol.getName(),
                 () -> {

smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java

@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.StringJoiner;
 import java.util.function.BiFunction;
+import java.util.function.UnaryOperator;
 import java.util.logging.Logger;
 import software.amazon.smithy.codegen.core.CodegenException;
 import software.amazon.smithy.codegen.core.Symbol;
@@ -210,15 +211,17 @@ public TypeScriptWriter writeDocs(String docs) {
     }
 
     /**
-     * Writes shape documentation comments if docs are present.
+     * Modifies and writes shape documentation comments if docs are present.
      *
      * @param shape Shape to write the documentation of.
+     * @param preprocessor UnaryOperator that takes documentation and returns modified one.
      * @return Returns true if docs were written.
      */
-    boolean writeShapeDocs(Shape shape) {
+    boolean writeShapeDocs(Shape shape, UnaryOperator<String> preprocessor) {
         return shape.getTrait(DocumentationTrait.class)
                 .map(DocumentationTrait::getValue)
                 .map(docs -> {
+                    docs = preprocessor.apply(docs);
                     if (shape.getTrait(DeprecatedTrait.class).isPresent()) {
                         docs = "@deprecated\n\n" + docs;
                     }
@@ -227,6 +230,16 @@ boolean writeShapeDocs(Shape shape) {
                 }).orElse(false);
     }
 
+    /**
+     * Writes shape documentation comments if docs are present.
+     *
+     * @param shape Shape to write the documentation of.
+     * @return Returns true if docs were written.
+     */
+    boolean writeShapeDocs(Shape shape) {
+        return writeShapeDocs(shape, (docs) -> docs);
+    }
+
     /**
      * Writes member shape documentation comments if docs are present.
      *

smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/UnionGenerator.java

@@ -242,6 +242,7 @@ private void writeVisitorFunction() {
 
     private void writeFilterSensitiveLog() {
         String objectParam = "obj";
+        writer.writeDocs("@internal");
         writer.openBlock("export const filterSensitiveLog = ($L: $L): any => {", "}",
             objectParam, symbol.getName(),
             () -> {