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..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 @@ -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" + + "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. 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/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. * 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(), () -> {