diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CodegenUtils.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CodegenUtils.java index c6a582ffc55..5b061362e1d 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CodegenUtils.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/CodegenUtils.java @@ -140,7 +140,7 @@ static void writeClientCommandStreamingInputType( ) { String memberName = streamingMember.getMemberName(); String optionalSuffix = streamingMember.isRequired() ? "" : "?"; - writer.openBlock("type $LType = Omit<$T, $S> & {", "};", typeName, + writer.openBlock("export type $LType = Omit<$T, $S> & {", "};", typeName, containerSymbol, memberName, () -> { writer.writeDocs(String.format("For *`%1$s[\"%2$s\"]`*, see {@link %1$s.%2$s}.", containerSymbol.getName(), memberName)); 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 88a62b0534e..1e4305ab03a 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 @@ -179,6 +179,8 @@ private String getCommandExample(String serviceName, String configName, String c + "const response = await client.send(command);\n" + "```\n" + "\n" + + String.format("@param %s - {@link %s}%n", commandInput, commandInput) + + String.format("@returns {@link %s}%n", commandOutput) + 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 %s's `config` shape.%n", configName, serviceName); @@ -205,13 +207,14 @@ private String getThrownExceptions() { } private void generateCommandConstructor() { - writer.openBlock("constructor(readonly input: $T) {", "}", inputType, () -> { - // The constructor can be intercepted and changed. - writer.write("// Start section: $L", COMMAND_CONSTRUCTOR_SECTION) - .pushState(COMMAND_CONSTRUCTOR_SECTION) - .write("super();") - .popState() - .write("// End section: $L", COMMAND_CONSTRUCTOR_SECTION); + writer.writeDocs("@public") + .openBlock("constructor(readonly input: $T) {", "}", inputType, () -> { + // The constructor can be intercepted and changed. + writer.write("// Start section: $L", COMMAND_CONSTRUCTOR_SECTION) + .pushState(COMMAND_CONSTRUCTOR_SECTION) + .write("super();") + .popState() + .write("// End section: $L", COMMAND_CONSTRUCTOR_SECTION); }); } @@ -356,7 +359,7 @@ private void addInputAndOutputTypes() { } private void writeInputType(String typeName, Optional inputShape, String commandName) { - writer.writeDocs("The input for {@link " + commandName + "}."); + writer.writeDocs("@public\n\nThe input for {@link " + commandName + "}."); if (inputShape.isPresent()) { StructureShape input = inputShape.get(); List blobStreamingMembers = getBlobStreamingMembers(model, input); @@ -373,7 +376,7 @@ private void writeInputType(String typeName, Optional inputShape } private void writeOutputType(String typeName, Optional outputShape, String commandName) { - writer.writeDocs("The output of {@link " + commandName + "}."); + writer.writeDocs("@public\n\nThe output of {@link " + commandName + "}."); // Output types should always be MetadataBearers, possibly in addition // to a defined output shape. writer.addImport("MetadataBearer", "__MetadataBearer", TypeScriptDependency.AWS_SDK_TYPES.packageName); @@ -414,26 +417,28 @@ private void addCommandSpecificPlugins() { private void writeSerde() { writer.write("") - .write("private serialize(") - .indent() - .write("input: $T,", inputType) - .write("context: $L", CodegenUtils.getOperationSerializerContextType(writer, model, operation)) - .dedent() - .openBlock( - "): Promise<$T> {", "}", - applicationProtocol.getRequestType(), - () -> writeSerdeDispatcher(true) - ); + .writeDocs("@internal") + .write("private serialize(") + .indent() + .write("input: $T,", inputType) + .write("context: $L", CodegenUtils.getOperationSerializerContextType(writer, model, operation)) + .dedent() + .openBlock( + "): Promise<$T> {", "}", + applicationProtocol.getRequestType(), + () -> writeSerdeDispatcher(true) + ); writer.write("") - .write("private deserialize(") - .indent() - .write("output: $T,", applicationProtocol.getResponseType()) - .write("context: $L", - CodegenUtils.getOperationDeserializerContextType(settings, writer, model, operation)) - .dedent() - .openBlock("): Promise<$T> {", "}", outputType, () -> writeSerdeDispatcher(false)) - .write(""); + .writeDocs("@internal") + .write("private deserialize(") + .indent() + .write("output: $T,", applicationProtocol.getResponseType()) + .write("context: $L", + CodegenUtils.getOperationDeserializerContextType(settings, writer, model, operation)) + .dedent() + .openBlock("): Promise<$T> {", "}", outputType, () -> writeSerdeDispatcher(false)) + .write(""); } private void writeSerdeDispatcher(boolean isInput) { diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/EnumGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/EnumGenerator.java index c0515aab223..fa82f9023b5 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/EnumGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/EnumGenerator.java @@ -81,18 +81,20 @@ public void run() { // Unnamed enums generate a union of string literals. private void generateUnnamedEnum() { String variants = TypeScriptUtils.getEnumVariants(enumTrait.getEnumDefinitionValues()); - writer.write("export type $L = $L", symbol.getName(), variants); + writer.writeDocs("@public") + .write("export type $L = $L", symbol.getName(), variants); } // Named enums generate an actual enum type. private void generateNamedEnum() { - writer.openBlock("export enum $L {", "}", symbol.getName(), () -> { - // Sort the named values to ensure a stable order and sane diffs. - // TODO: Should we just sort these in the trait itself? - enumTrait.getValues() - .stream() - .sorted(Comparator.comparing(e -> e.getName().get())) - .forEach(this::writeNamedEnumConstant); + writer.writeDocs("@public") + .openBlock("export enum $L {", "}", symbol.getName(), () -> { + // Sort the named values to ensure a stable order and sane diffs. + // TODO: Should we just sort these in the trait itself? + enumTrait.getValues() + .stream() + .sorted(Comparator.comparing(e -> e.getName().get())) + .forEach(this::writeNamedEnumConstant); }); } diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/PaginationGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/PaginationGenerator.java index 735b0cfc2a9..797d82f8640 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/PaginationGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/PaginationGenerator.java @@ -119,7 +119,8 @@ static void generateServicePaginationInterfaces( writer.addImport("PaginationConfiguration", "PaginationConfiguration", "@aws-sdk/types"); writer.addImport(service.getName(), service.getName(), service.getNamespace()); - writer.openBlock("export interface $LPaginationConfiguration extends PaginationConfiguration {", + writer.writeDocs("@public") + .openBlock("export interface $LPaginationConfiguration extends PaginationConfiguration {", "}", aggregatedClientName, () -> { writer.write("client: $L;", service.getName()); }); @@ -166,7 +167,8 @@ private void writePager() { String inputTokenName = paginatedInfo.getPaginatedTrait().getInputToken().get(); String outputTokenName = paginatedInfo.getPaginatedTrait().getOutputToken().get(); - writer.openBlock( + writer.writeDocs("@public") + .openBlock( "export async function* paginate$L(config: $L, input: $L, ...additionalArguments: any): Paginator<$L>{", "}", operationName, paginationType, inputTypeName, outputTypeName, () -> { String destructuredInputTokenName = destructurePath(inputTokenName); @@ -209,7 +211,7 @@ private void writePager() { * environments and does not generally expose the entire service. */ private void writeCommandRequest() { - writer.writeDocs("@private"); + writer.writeDocs("@internal"); writer.openBlock( "const makePagedClientRequest = async (client: $L, input: $L, ...args: any): Promise<$L> => {", "}", serviceSymbol.getName(), inputSymbol.getName(), diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/ServiceBareBonesClientGenerator.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/ServiceBareBonesClientGenerator.java index 2cbd1c62430..529c97ec112 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/ServiceBareBonesClientGenerator.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/ServiceBareBonesClientGenerator.java @@ -132,6 +132,7 @@ private void writeInputOutputTypeUnion( .sorted(Comparator.comparing(Symbol::getName)) .collect(Collectors.toList()); + writer.writeDocs("@public"); writer.write("export type $L = ", typeName); writer.indent(); // If we have less symbols than operations, at least one doesn't have a type, so add the default. @@ -154,6 +155,7 @@ private void generateConfig() { generateClientDefaults(); + writer.writeDocs("@public"); // The default configuration type is always just the base-level // Smithy configuration requirements. writer.write("type $LType = Partial<__SmithyConfiguration<$T>>", configType, @@ -183,13 +185,14 @@ private void generateConfig() { writer.dedent(); } - writer.writeDocs(String.format("The configuration interface of %s class constructor that set the region, " - + "credentials and other options.", symbol.getName())); + writer.writeDocs(String.format("%s The configuration interface of %s class constructor that set the region, " + + "credentials and other options.", "@public\n\n", symbol.getName())); writer.write("export interface $1L extends $1LType {}", configType); // Generate the corresponding "Resolved" configuration type to account for // each "Input" configuration type. writer.write(""); + writer.writeDocs("@public"); writer.write("type $LType = __SmithyResolvedConfiguration<$T>", resolvedConfigType, applicationProtocol.getOptionsType()); writer.write(" & Required"); @@ -212,9 +215,9 @@ private void generateConfig() { writer.dedent(); } - writer.writeDocs(String.format("The resolved configuration interface of %s class. This is resolved and" - + " normalized from the {@link %s | constructor configuration interface}.", symbol.getName(), - configType)); + writer.writeDocs(String.format("%s The resolved configuration interface of %s class. This is resolved and" + + " normalized from the {@link %s | constructor configuration interface}.", "@public\n\n", + symbol.getName(), configType)); writer.write("export interface $1L extends $1LType {}", resolvedConfigType); writer.popState(); @@ -226,7 +229,8 @@ private void generateClientDefaults() { "Protocols other than HTTP are not yet implemented: " + applicationProtocol); } - writer.openBlock("export interface ClientDefaults\n" + writer.writeDocs("@public") + .openBlock("export interface ClientDefaults\n" + " extends Partial<__SmithyResolvedConfiguration<$T>> {", "}", applicationProtocol.getOptionsType(), () -> { writer.addImport("HttpHandler", "__HttpHandler", "@aws-sdk/protocol-http"); @@ -238,9 +242,10 @@ private void generateClientDefaults() { writer.addImport("Checksum", "__Checksum", "@aws-sdk/types"); writer.addImport("ChecksumConstructor", "__ChecksumConstructor", "@aws-sdk/types"); - writer.writeDocs("A constructor for a class implementing the {@link __Checksum} interface \n" - + "that computes the SHA-256 HMAC or checksum of a string or binary buffer.\n" - + "@internal"); + writer.writeDocs("A constructor for a class implementing the {@link @aws-sdk/types#ChecksumConstructor} " + + "interface \n" + + "that computes the SHA-256 HMAC or checksum of a string or binary buffer.\n" + + "@internal"); writer.write("sha256?: __ChecksumConstructor | __HashConstructor;\n"); writer.addImport("UrlParser", "__UrlParser", "@aws-sdk/types"); 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 cef09ac0c09..05d845b7ed5 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 @@ -27,6 +27,7 @@ import software.amazon.smithy.model.shapes.Shape; import software.amazon.smithy.model.traits.DeprecatedTrait; import software.amazon.smithy.model.traits.DocumentationTrait; +import software.amazon.smithy.model.traits.InternalTrait; import software.amazon.smithy.utils.SmithyUnstableApi; import software.amazon.smithy.utils.StringUtils; @@ -155,10 +156,14 @@ boolean writeShapeDocs(Shape shape, UnaryOperator preprocessor) { return shape.getTrait(DocumentationTrait.class) .map(DocumentationTrait::getValue) .map(docs -> { + // Escape valid '{' and '}' + docs = docs.replace("{", "\\{") + .replace("}", "\\}"); docs = preprocessor.apply(docs); if (shape.getTrait(DeprecatedTrait.class).isPresent()) { docs = "@deprecated\n\n" + docs; } + docs = writeReleaseTag(shape, docs); writeDocs(docs); return true; }).orElse(false); @@ -171,7 +176,11 @@ boolean writeShapeDocs(Shape shape, UnaryOperator preprocessor) { * @return Returns true if docs were written. */ boolean writeShapeDocs(Shape shape) { - return writeShapeDocs(shape, (docs) -> docs); + boolean didWrite = writeShapeDocs(shape, (docs) -> docs); + if (!didWrite) { + writeDocs("@public"); + } + return didWrite; } /** @@ -185,9 +194,13 @@ boolean writeMemberDocs(Model model, MemberShape member) { return member.getMemberTrait(model, DocumentationTrait.class) .map(DocumentationTrait::getValue) .map(docs -> { + // Escape valid '{' and '}' + docs = docs.replace("{", "\\{") + .replace("}", "\\}"); if (member.getTrait(DeprecatedTrait.class).isPresent() || isTargetDeprecated(model, member)) { docs = "@deprecated\n\n" + docs; } + writeReleaseTag(member, docs); writeDocs(docs); return true; }).orElse(false); @@ -199,6 +212,15 @@ private boolean isTargetDeprecated(Model model, MemberShape member) { && !Prelude.isPreludeShape(member.getTarget()); } + private String writeReleaseTag(Shape shape, String docs) { + if (shape.getTrait(InternalTrait.class).isPresent()) { + docs = "@internal\n" + docs; + } else { + docs = "@public\n" + docs; + } + return docs; + } + @Override public String toString() { String contents = super.toString(); 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 a2231cfe333..17c8d538cad 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 @@ -174,14 +174,15 @@ public void run() { }); // Write out the namespace that contains each variant and visitor. - writer.openBlock("export namespace $L {", "}", symbol.getName(), () -> { - writeUnionMemberInterfaces(); - writeVisitorType(); - writeVisitorFunction(); - if (includeValidation) { - writeValidate(); - } - }); + writer.writeDocs("@public") + .openBlock("export namespace $L {", "}", symbol.getName(), () -> { + writeUnionMemberInterfaces(); + writeVisitorType(); + writeVisitorFunction(); + if (includeValidation) { + writeValidate(); + } + }); writeFilterSensitiveLog(symbol.getName()); } diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddBaseServiceExceptionClass.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddBaseServiceExceptionClass.java index 32675eed818..bf54eb10daf 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddBaseServiceExceptionClass.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddBaseServiceExceptionClass.java @@ -68,7 +68,7 @@ private void writeAdditionalFiles( TypeScriptDependency.AWS_SMITHY_CLIENT.packageName); writer.addImport("ServiceExceptionOptions", "__ServiceExceptionOptions", TypeScriptDependency.AWS_SMITHY_CLIENT.packageName); - writer.writeDocs("Base exception class for all service exceptions from " + writer.writeDocs("@public\n\nBase exception class for all service exceptions from " + serviceName + " service."); writer.openBlock("export class $L extends __ServiceException {", serviceExceptionName); writer.writeDocs("@internal"); diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddDefaultsModeDependency.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddDefaultsModeDependency.java index dac123d812f..40be09864fb 100644 --- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddDefaultsModeDependency.java +++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/integration/AddDefaultsModeDependency.java @@ -39,7 +39,8 @@ public void addConfigInterfaceFields( writer.addDependency(TypeScriptDependency.AWS_SDK_UTIL_DEFAULTS_MODE_NODE); writer.addImport("DefaultsMode", "__DefaultsMode", TypeScriptDependency.AWS_SMITHY_CLIENT.packageName); writer.addImport("Provider", "__Provider", TypeScriptDependency.AWS_SDK_TYPES.packageName); - writer.writeDocs("The {@link __DefaultsMode} that will be used to determine how certain default configuration " + writer.writeDocs("The {@link @aws-sdk/smithy-client#DefaultsMode} that " + + "will be used to determine how certain default configuration " + "options are resolved in the SDK."); writer.write("defaultsMode?: __DefaultsMode | __Provider<__DefaultsMode>;\n"); }