Add TSDoc release tags

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));

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<StructureShape> 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<MemberShape> blobStreamingMembers = getBlobStreamingMembers(model, input);
@@ -373,7 +376,7 @@ private void writeInputType(String typeName, Optional<StructureShape> inputShape
     }
 
     private void writeOutputType(String typeName, Optional<StructureShape> 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) {

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);
         });
     }
 

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(),

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<ClientDefaults>");
@@ -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");

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<String> 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<String> 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();

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());
     }
 

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");

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");
     }