From 68357988ffa86ba71bbae261329f8b4a5828710f Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Thu, 29 Apr 2021 15:59:52 -0700 Subject: [PATCH 1/3] mark filterSensitiveLog as internal --- .../amazon/smithy/typescript/codegen/StructureGenerator.java | 1 + .../amazon/smithy/typescript/codegen/UnionGenerator.java | 1 + 2 files changed, 2 insertions(+) diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/StructureGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/StructureGenerator.java index 4e751c311c7..51012513dce 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/StructureGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/StructureGenerator.java @@ -167,6 +167,7 @@ private void renderStructureNamespace() { 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(), () -> { diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/UnionGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/UnionGenerator.java index e0413c0be0b..78a3f88f1a6 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/UnionGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/UnionGenerator.java @@ -224,6 +224,7 @@ private void writeVisitorFunction() { private void writeFilterSensitiveLog() { String objectParam = "obj"; + writer.writeDocs("@internal"); writer.openBlock("export const filterSensitiveLog = ($L: $L): any => {", "}", objectParam, symbol.getName(), () -> { From 39784e48b9b48d6e8bf7390ba65c2c864cdb72ed Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Sun, 2 May 2021 18:48:51 -0700 Subject: [PATCH 2/3] generate example for using bare-bone client and command API also makes filterSensitive internal --- .../typescript/codegen/CommandGenerator.java | 23 ++++++++++++++++++- .../typescript/codegen/TypeScriptWriter.java | 17 ++++++++++++-- 2 files changed, 37 insertions(+), 3 deletions(-) diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java index 2bcc336ff8d..da27756e91d 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java @@ -105,7 +105,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, () -> { @@ -128,6 +129,26 @@ private void generateClientCommand() { }); } + private String getCommandExample(String serviceName, String configName, String commandName, String commandInput, + String commandOutput) { + String packageName = settings.getPackageName(); + return "@example\n" + + "User 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. diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java index b96272e49c8..a7388aea0b5 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java +++ b/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; @@ -208,15 +209,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 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; } @@ -225,6 +228,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. * From 014247d21c2e9d1a584c5f8518e945094cfa46aa Mon Sep 17 00:00:00 2001 From: Allan Zheng Date: Wed, 5 May 2021 17:11:05 -0700 Subject: [PATCH 3/3] fix typo --- .../amazon/smithy/typescript/codegen/CommandGenerator.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java index da27756e91d..34cd74b9adc 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CommandGenerator.java @@ -133,7 +133,7 @@ private String getCommandExample(String serviceName, String configName, String c String commandOutput) { String packageName = settings.getPackageName(); return "@example\n" - + "User a bare-bones client and the command you need to make an API call.\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)