Incorporate documentation feedback

smithy-lang · Jun 23, 2021 · 91014fc · 91014fc
1 parent 88db25e
commit 91014fc
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 43 deletions.
diff --git a/docs/source/1.0/spec/aws/customizations/s3-customizations.rst b/docs/source/1.0/spec/aws/customizations/s3-customizations.rst
@@ -134,37 +134,19 @@ resolved to "virtual" to enable this setting.
 S3 Traits
 =========
 
-``s3UnwrappedXmlOutput`` trait
-------------------------------
+``aws.customizations#s3UnwrappedXmlOutput`` trait
+-------------------------------------------------
 
 Summary
-    Indicates the response output is not wrapped in an operation-level XML tag.
+    Indicates the response body from S3 is not wrapped in the :ref:`aws-restxml-protocol` operation-level XML node.
 
 Trait selector
-    .. code-block:: none
+    ``operation``
 
-        operation
-
-    *An operation*
 Value type
     Annotation trait
 
-This trait indicates the response output is not wrapped in an operation-level tag.
-For example, rather than having some data wrapped in `SomeOperationResult` as shown below,
-
-.. code-block:: xml
-
-    <SomeOperationResult>
-        <ActualData>something</ActualData>
-    </SomeOperationResult>
-
-We have the data directly in the top-level:
-
-.. code-block:: xml
-
-    <ActualData>something</ActualData>
-
-Given the following:
+Consider the following *abridged* model of S3's ``GetBucketLocation`` operation:
 
 .. tabs::
 
@@ -231,12 +213,21 @@ Given the following:
             }
         }
 
-We expect the following response shape:
+Since this operation is modeled with ``@s3UnwrappedXmlOutput``,
+an Amazon S3 client should expect the response from S3 to be unwrapped as shown below:
+
+.. code-block:: xml
+
+    <LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">us-west-2</LocationConstraint>
+
+Without ``@s3UnwrappedXmlOutput`` on the operation, the response would be expected to be
+wrapped with the :ref:`aws-restxml-protocol` operation-level XML node:
 
 .. code-block:: xml
 
-    <LocationConstraint>us-west-2</LocationConstraint>
+    <LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
+        <LocationConstraint>us-west-2</LocationConstraint>
+    </LocationConstraint>
 
-Client code generated from Smithy for Amazon S3 MUST understand the `@s3UnwrappedXmlOutput` trait
-in order to properly handle the output for the `GetBucketLocation` operation, which has an unwrapped
-response that looks like the example above.
+A client for Amazon S3 MUST understand the ``@s3UnwrappedXmlOutput`` trait
+in order to properly handle the output for the ``GetBucketLocation`` operation.
diff --git a/smithy-aws-protocol-tests/model/restXml/services/s3.smithy b/smithy-aws-protocol-tests/model/restXml/services/s3.smithy
@@ -270,6 +270,27 @@ operation ListObjectsV2 {
     ],
 }
 
+
+@httpResponseTests([{
+        id: "GetBucketLocationUnwrappedOutput",
+        documentation: """
+            S3 clients should use the @s3UnwrappedXmlOutput trait to determine
+            that the response shape is not wrapped in a restxml operation-level XML node.
+        """,
+        code: 200,
+        body: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<LocationConstraint xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">us-west-2</LocationConstraint>",
+        params: {
+            "LocationConstraint": "us-west-2"
+        },
+        protocol: restXml
+}])
+@http(uri: "/GetBucketLocation", method: "GET")
+@s3UnwrappedXmlOutput
+operation GetBucketLocation {
+    output: GetBucketLocationOutput,
+}
+
+
 structure CommonPrefix {
     Prefix: Prefix,
 }
@@ -465,17 +486,3 @@ structure GetBucketLocationOutput {
     LocationConstraint: BucketLocationConstraint,
 }
 
-@httpResponseTests([{
-        id: "GetBucketLocation",
-        code: 200,
-        body: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<LocationConstraint xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\">us-west-2</LocationConstraint>",
-        params: {
-            "LocationConstraint": "us-west-2"
-        },
-        protocol: "aws.protocols#restXml"
-}])
-@http(uri: "/GetBucketLocation", method: "GET")
-@s3UnwrappedXmlOutput
-operation GetBucketLocation {
-    output: GetBucketLocationOutput,
-}
diff --git a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.customizations.json b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.customizations.json
@@ -8,7 +8,7 @@
                 "smithy.api#trait": {
                     "selector": "operation"
                 },
-                "smithy.api#documentation": "Unwraps the output for a XML response. Intended to only be used by AWS S3."
+                "smithy.api#documentation": "Indicates the response body from S3 is not wrapped in the aws-restxml-protocol operation-level XML node. Intended to only be used by AWS S3."
             }
         }
     }