Update AWS protocol documentation

docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst

@@ -35,11 +35,6 @@ Value type
 
     This protocol does not support document types.
 
-.. important::
-
-    This protocol only permits the :ref:`httpPayload-trait` to be applied to
-    members that target structures, documents, strings, blobs, or unions.
-
 .. tabs::
 
     .. code-tab:: smithy

docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst

@@ -25,10 +25,40 @@ Summary
 Trait selector
     ``service``
 Value type
-    Annotation trait.
+    Structure
 See
     `Protocol tests <https://github.com/awslabs/smithy/tree/__smithy_version__/smithy-aws-protocol-tests/model/awsJson1_0>`_
 
+``aws.protocols#awsJson1_0`` is a structure that supports the following
+members:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 10 20 70
+
+    * - Property
+      - Type
+      - Description
+    * - http
+      - ``[string]``
+      - The priority ordered list of supported HTTP protocol versions.
+    * - eventStreamHttp
+      - ``[string]``
+      - The priority ordered list of supported HTTP protocol versions
+        that are required when using :ref:`event streams <event-streams>`
+        with the service. If not set, this value defaults to the value
+        of the ``http`` member. Any entry in ``eventStreamHttp`` MUST
+        also appear in ``http``.
+
+Each entry in ``http`` and ``eventStreamHttp`` SHOULD be a valid
+`Application-Layer Protocol Negotiation (ALPN) Protocol ID`_ (for example,
+``http/1.1``, ``h2``, etc). Clients SHOULD pick the first protocol in the
+list they understand when connecting to a service. A client SHOULD assume
+that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp``
+values are provided.
+
+The following example defines a service that uses ``aws.protocols#awsJson1_0``.
+
 .. tabs::
 
     .. code-tab:: smithy
@@ -57,8 +87,59 @@ See
             }
         }
 
+The following example defines a service that requires the use of
+``h2`` when using event streams.
+
+.. code-block:: smithy
+
+    namespace smithy.example
+
+    use aws.protocols#awsJson1_0
+
+    @awsJson1_0(
+        http: ["h2", "http/1.1"],
+        eventStreamHttp: ["h2"]
+    )
+    service MyService {
+        version: "2020-02-05"
+    }
+
+The following example defines a service that requires the use of
+``h2`` or ``http/1.1`` when using event streams, where ``h2`` is
+preferred over ``http/1.1``.
+
+.. code-block:: smithy
+
+    namespace smithy.example
+
+    use aws.protocols#awsJson1_0
+
+    @awsJson1_1(
+        http: ["h2", "http/1.1"],
+        eventStreamHttp: ["h2", "http/1.1"]
+    )
+    service MyService {
+        version: "2020-02-05"
+    }
+
+The following example defines a service that requires the use of
+``h2`` for all requests, including event streams.
+
+.. code-block:: smithy
+
+    namespace smithy.example
+
+    use aws.protocols#awsJson1_0
+
+    @awsJson1_0(http: ["h2"])
+    service MyService {
+        version: "2020-02-05"
+    }
+
 .. |quoted shape name| replace:: ``awsJson1_0``
 .. |protocol content type| replace:: ``application/x-amz-json-1.0``
 .. |protocol error type contents| replace:: :ref:`shape-id`
 .. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_0
 .. include:: aws-json.rst.template
+
+.. _`Application-Layer Protocol Negotiation (ALPN) Protocol ID`: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst

@@ -25,10 +25,40 @@ Summary
 Trait selector
     ``service``
 Value type
-    Annotation trait.
+    Structure
 See
     `Protocol tests <https://github.com/awslabs/smithy/tree/__smithy_version__/smithy-aws-protocol-tests/model/awsJson1_1>`_
 
+``aws.protocols#awsJson1_1`` is a structure that supports the following
+members:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 10 20 70
+
+    * - Property
+      - Type
+      - Description
+    * - http
+      - ``[string]``
+      - The priority ordered list of supported HTTP protocol versions.
+    * - eventStreamHttp
+      - ``[string]``
+      - The priority ordered list of supported HTTP protocol versions
+        that are required when using :ref:`event streams <event-streams>`
+        with the service. If not set, this value defaults to the value
+        of the ``http`` member. Any entry in ``eventStreamHttp`` MUST
+        also appear in ``http``.
+
+Each entry in ``http`` and ``eventStreamHttp`` SHOULD be a valid
+`Application-Layer Protocol Negotiation (ALPN) Protocol ID`_ (for example,
+``http/1.1``, ``h2``, etc). Clients SHOULD pick the first protocol in the
+list they understand when connecting to a service. A client SHOULD assume
+that a service supports ``http/1.1`` when no ``http`` or ``eventStreamHttp``
+values are provided.
+
+The following example defines a service that uses ``aws.protocols#awsJson1_1``.
+
 .. tabs::
 
     .. code-tab:: smithy
@@ -57,8 +87,59 @@ See
             }
         }
 
+The following example defines a service that requires the use of
+``h2`` when using event streams.
+
+.. code-block:: smithy
+
+    namespace smithy.example
+
+    use aws.protocols#awsJson1_1
+
+    @awsJson1_1(
+        http: ["h2", "http/1.1"],
+        eventStreamHttp: ["h2"]
+    )
+    service MyService {
+        version: "2020-02-05"
+    }
+
+The following example defines a service that requires the use of
+``h2`` or ``http/1.1`` when using event streams, where ``h2`` is
+preferred over ``http/1.1``.
+
+.. code-block:: smithy
+
+    namespace smithy.example
+
+    use aws.protocols#awsJson1_1
+
+    @awsJson1_1(
+        http: ["h2", "http/1.1"],
+        eventStreamHttp: ["h2", "http/1.1"]
+    )
+    service MyService {
+        version: "2020-02-05"
+    }
+
+The following example defines a service that requires the use of
+``h2`` for all requests, including event streams.
+
+.. code-block:: smithy
+
+    namespace smithy.example
+
+    use aws.protocols#awsJson1_1
+
+    @awsJson1_1(http: ["h2"])
+    service MyService {
+        version: "2020-02-05"
+    }
+
 .. |quoted shape name| replace:: ``awsJson1_1``
 .. |protocol content type| replace:: ``application/x-amz-json-1.1``
 .. |protocol error type contents| replace:: :token:`shape name <smithy:identifier>`
 .. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_1
 .. include:: aws-json.rst.template
+
+.. _`Application-Layer Protocol Negotiation (ALPN) Protocol ID`: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids

docs/source/1.0/spec/aws/aws-restjson1-protocol.rst

@@ -98,7 +98,10 @@ The following example defines a service that requires the use of
 
     use aws.protocols#restJson1
 
-    @restJson1(eventStreamHttp: ["h2"])
+    @restJson1(
+        http: ["h2", "http/1.1"],
+        eventStreamHttp: ["h2"]
+    )
     service MyService {
         version: "2020-04-02"
     }
@@ -113,7 +116,10 @@ preferred over ``http/1.1``.
 
     use aws.protocols#restJson1
 
-    @restJson1(eventStreamHttp: ["h2", "http/1.1"])
+    @awsJson1_1(
+        http: ["h2", "http/1.1"],
+        eventStreamHttp: ["h2", "http/1.1"]
+    )
     service MyService {
         version: "2020-04-02"
     }
@@ -315,8 +321,7 @@ standard responses with one additional component to distinguish which error
 is contained. New server-side protocol implementations MUST use a header field
 named ``X-Amzn-Errortype``. Clients MUST accept any one of the following: an
 additional header with the name ``X-Amzn-Errortype``, a body field with the
-name ``__type``, or a body field named ``code
-``. The value of this component
+name ``__type``, or a body field named ``code``. The value of this component
 SHOULD contain only the :token:`shape name <smithy:identifier>` of the error's
 :ref:`shape-id`.