docs: improve deprecatedTrait with default description (#1541)

Author: aBurmeseDev

private/my-local-model/src/commands/GetNumbersCommand.ts

@@ -40,6 +40,8 @@ export interface GetNumbersCommandOutput extends GetNumbersResponse, __MetadataB
  * const input = { // GetNumbersRequest
  *   bigDecimal: Number("bigdecimal"),
  *   bigInteger: Number("bigint"),
+ *   fieldWithoutMessage: "STRING_VALUE",
+ *   fieldWithMessage: "STRING_VALUE",
  * };
  * const command = new GetNumbersCommand(input);
  * const response = await client.send(command);

private/my-local-model/src/models/models_0.ts

@@ -39,6 +39,21 @@ export class CodedThrottlingError extends __BaseException {
 export interface GetNumbersRequest {
   bigDecimal?: NumericValue | undefined;
   bigInteger?: bigint | undefined;
+  /**
+   * This is deprecated documentation annotation
+   *
+   * @deprecated deprecated
+   * @public
+   */
+  fieldWithoutMessage?: string | undefined;
+
+  /**
+   * This is deprecated documentation annotation
+   *
+   * @deprecated This field has been deprecated
+   * @public
+   */
+  fieldWithMessage?: string | undefined;
 }
 
 /**

private/my-local-model/src/protocols/Rpcv2cbor.ts

@@ -296,6 +296,8 @@ const se_GetNumbersRequest = (input: GetNumbersRequest, context: __SerdeContext)
   return take(input, {
     bigDecimal: __nv,
     bigInteger: [],
+    fieldWithMessage: [],
+    fieldWithoutMessage: [],
   });
 };
 

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

@@ -225,10 +225,9 @@ boolean writeShapeDocs(Shape shape, UnaryOperator<String> preprocessor) {
                     if (shape.getTrait(DeprecatedTrait.class).isPresent()) {
                         DeprecatedTrait deprecatedTrait = shape.expectTrait(DeprecatedTrait.class);
                         String deprecationMessage = deprecatedTrait.getMessage()
-                            .map(msg -> " " + msg)
-                            .orElse("");
-                        String deprecationString = "@deprecated" + deprecationMessage;
-                        docs = docs + "\n\n" + deprecationString;
+                            .orElse("deprecated");
+                        String deprecationAnnotation = "@deprecated " + deprecationMessage;
+                        docs = docs + "\n\n" + deprecationAnnotation;
                     }
                     docs = preprocessor.apply(docs);
                     docs = addReleaseTag(shape, docs);
@@ -266,7 +265,13 @@ boolean writeMemberDocs(Model model, MemberShape member) {
                     docs = docs.replace("{", "\\{")
                         .replace("}", "\\}");
                     if (member.getTrait(DeprecatedTrait.class).isPresent() || isTargetDeprecated(model, member)) {
-                        docs = docs + "\n\n@deprecated";
+                        DeprecatedTrait deprecatedTrait = member.getTrait(DeprecatedTrait.class)
+                            .or(() -> model.expectShape(member.getTarget()).getTrait(DeprecatedTrait.class))
+                            .orElseThrow();
+                        String deprecationMessage = deprecatedTrait.getMessage()
+                            .orElse("deprecated");
+                        String deprecationAnnotation = "@deprecated " + deprecationMessage;
+                        docs = docs + "\n\n" + deprecationAnnotation;
                     }
                     docs = addReleaseTag(member, docs);
                     writeDocs(docs);

smithy-typescript-protocol-test-codegen/model/my-local-model/main.smithy

@@ -29,7 +29,16 @@ operation GetNumbers {
 @input
 structure GetNumbersRequest {
     bigDecimal: BigDecimal
+
     bigInteger: BigInteger
+
+    @documentation("This is deprecated documentation annotation")
+    @deprecated
+    fieldWithoutMessage: String
+
+    @documentation("This is deprecated documentation annotation")
+    @deprecated(message: "This field has been deprecated", since: "3.0")
+    fieldWithMessage: String
 }
 
 @output