Update design documentation (#536)

Co-authored-by: Russell Cohen <rcoh@amazon.com>

design/src/smithy/aggregate_shapes.md

@@ -55,13 +55,11 @@ long WriteIOs
 ```rust,ignore
 /// <p>Contains I/O usage metrics for a command that was invoked.</p>
 #[non_exhaustive]
-#[derive(serde::Deserialize, serde::Serialize, std::clone::Clone, std::cmp::PartialEq)]
+#[derive(std::clone::Clone, std::cmp::PartialEq)]
 pub struct IOUsage {
     /// <p>The number of read I/O requests that the command made.</p>
-    #[serde(rename = "ReadIOs")]
     pub read_i_os: i64,
     /// <p>The number of write I/O requests that the command made.</p>
-    #[serde(rename = "WriteIOs")]
     pub write_i_os: i64,
 }
 impl std::fmt::Debug for IOUsage {
@@ -163,26 +161,26 @@ pub enum AttributeValue {
 }
 
 impl AttributeValue {
-    pub fn as_bool(&self) -> Option<&bool> {
-        if let AttributeValue::Bool(val) = &self { Some(&val) } else { None }
+    pub fn as_bool(&self) -> Result<&bool, &crate::model::AttributeValue> {
+        if let AttributeValue::Bool(val) = &self { Ok(&val) } else { Err(self) }
     }
     pub fn is_bool(&self) -> bool {
         self.as_bool().is_some()
     }
-    pub fn as_bools(&self) -> Option<&std::vec::Vec<bool>> {
-        if let AttributeValue::Bools(val) = &self { Some(&val) } else { None }
+    pub fn as_bools(&self) -> Result<&std::vec::Vec<bool>, &crate::model::AttributeValue> {
+        if let AttributeValue::Bools(val) = &self { Ok(&val) } else { Err(self) }
     }
     pub fn is_bools(&self) -> bool {
         self.as_bools().is_some()
     }
-    pub fn as_map(&self) -> Option<&std::collections::HashMap<std::string::String, crate::model::AttributeValue>> {
-        if let AttributeValue::Map(val) = &self { Some(&val) } else { None }
+    pub fn as_map(&self) -> Result<&std::collections::HashMap<std::string::String, crate::model::AttributeValue>, &crate::model::AttributeValue> {
+        if let AttributeValue::Map(val) = &self { Ok(&val) } else { Err(self) }
     }
     pub fn is_map(&self) -> bool {
         self.as_map().is_some()
     }
-    pub fn as_string(&self) -> Option<&std::string::String> {
-        if let AttributeValue::String(val) = &self { Some(&val) } else { None }
+    pub fn as_string(&self) -> Result<&std::string::String, &crate::model::AttributeValue> {
+        if let AttributeValue::String(val) = &self { Ok(&val) } else { Err(self) }
     }
     pub fn is_string(&self) -> bool {
         self.as_string().is_some()

design/src/smithy/recursive_shapes.md

@@ -1,5 +1,5 @@
 # Recursive Shapes
-> NB: Throughout this document, the word "box" always refers to a Rust [`Box<T>`](https://doc.rust-lang.org/std/boxed/struct.Box.html), a heap allocated pointer to T, and not the Smithy concept of boxed vs. unboxed.
+> Note: Throughout this document, the word "box" always refers to a Rust [`Box<T>`](https://doc.rust-lang.org/std/boxed/struct.Box.html), a heap allocated pointer to T, and not the Smithy concept of boxed vs. unboxed.
 
 Recursive shapes pose a problem for Rust, because the following Rust code will not compile:
 

design/src/smithy/simple_shapes.md

@@ -13,7 +13,7 @@
 | [bigInteger](#big-numbers) | `BigInteger` (Not implemented yet) |
 | [bigDecimal](#big-numbers) | `BigDecimal` (Not implemented yet) |
 | [timestamp](#timestamps)  | [`Instant`](https://github.com/awslabs/smithy-rs/blob/main/rust-runtime/smithy-types/src/instant/mod.rs) |
-| [document](#documents) | `Document` (https://github.com/awslabs/smithy-rs/blob/v0.6-rc.1/rust-runtime/smithy-types/src/lib.rs#L33-L41) |
+| [document](#documents) | [`Document`](https://github.com/awslabs/smithy-rs/blob/v0.14/rust-runtime/smithy-types/src/lib.rs#L38-L52) |
 
 ### Big Numbers
 Rust currently has no standard library or universally accepted large-number crate. Until one is stabilized, a string representation is a reasonable compromise:
@@ -25,7 +25,7 @@ pub struct BigDecimal(String);
 
 This will enable us to add helpers over time as requested. Users will also be able to define their own conversions into their preferred large-number libraries.
 
-As of 4/17/2021 BigInteger / BigDecimal are not included in AWS models. Implementation is tracked [here](https://github.com/awslabs/smithy-rs/issues/312).
+As of 5/23/2021 BigInteger / BigDecimal are not included in AWS models. Implementation is tracked [here](https://github.com/awslabs/smithy-rs/issues/312).
 ### Timestamps
 [chrono](https://github.com/chronotope/chrono) is the current de facto library for datetime in Rust, but it is pre-1.0. Instants are represented by an SDK defined structure modeled on `std::time::Duration` from the Rust standard library.
 
@@ -55,4 +55,4 @@ Smithy defines the concept of "Document Types":
 {{#include ../../../rust-runtime/smithy-types/src/lib.rs:document}}
 ```
 
-Individual protocols define their own document serialization behavior, typically by creating a newtype around `Document` that implements `serde::Serialize/serde::Deserialize`. See [Document Json Serialization](https://github.com/awslabs/smithy-rs/blob/138320e99e6c7aaf14217d07cf996ba07349dd5e/rust-runtime/inlineable/src/doc_json.rs)
+Individual protocols define their own document serialization behavior, with some protocols such as AWS and EC2 Query not supporting document types.

design/src/tenets.md

@@ -1,6 +1,6 @@
 # Rust SDK Design Tenets
 > Unless you know better ones! These are our tenets today, but we'd love your thoughts. Do you wish we had different priorities? Let us know by opening and issue or starting a discussion.
-1. [**Batteries included, but replaceable.**](#batteries-included-but-replaceable) The AWS SDK for Rust should provide a best-in-class experience for many use cases, **but**, customers will use the SDK in unqiue and unexpected ways. **Meet customers where they are;** strive to be compatible with their tools. Provide mechanisms to allow customers make different choices.
+1. [**Batteries included, but replaceable.**](#batteries-included-but-replaceable) The AWS SDK for Rust should provide a best-in-class experience for many use cases, **but**, customers will use the SDK in unique and unexpected ways. **Meet customers where they are;** strive to be compatible with their tools. Provide mechanisms to allow customers make different choices.
 2. [**Make common problems easy to solve.**](#make-common-problems-easy-to-solve) The AWS SDK for Rust should uncommon problems solvable. Guide customers to patterns that set them up for long-term success.
 3. [**Design for the Future.**](#design-for-the-future) The AWS SDK for Rust should evolve with AWS without breaking existing customers. APIs will evolve in unpredictable directions, new protocols will gain adoption, and new services will be created that we never could have imagined. Don’t simplify or unify code today that prevents evolution tomorrow.