Added docs for flattening

This adds docs for the `#[serde(flatten)]` featur from this pull
request: serde-rs/serde#1179

Author: mitsuhiko

_src/SUMMARY.md

@@ -23,6 +23,7 @@
     * [Enum representations](enum-representations.md)
     * [Borrowing data](borrow.md)
     * [Default value for a field](attr-default.md)
+    * [Struct flattening](attr-flatten.md)
     * [Handwritten generic type bounds](attr-bound.md)
     * [Deserialize for custom map type](deserialize-map.md)
     * [Array of values without buffering](stream-array.md)

_src/attr-flatten.md

@@ -0,0 +1,66 @@
+# Struct flattening
+
+Limited support for flattening of data is supported by serde through the `#[serde(flatten)]`
+attribute.  It can be used for a variety of common purposes when working with JSON data
+in particular.
+
+## Refactor common elements
+
+For instance flatten can be used to move common
+
+```rust
+#[derive(Serialize, Deserialize, Debug)]
+struct PaginatedResponse<U> {
+    #[serde(flatten)]
+    pagination: Pagination,
+    items: Vec<U>
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Pagination {
+    limit: u64,
+    offset: u64,
+    total: u64,
+}
+
+#[derive(Serialize, Deserialize, Debug)]
+struct User {
+    id: String,
+    username: String,
+    email: Option<String>,
+}
+```
+
+Then `PaginatedResponse<User>` can be deserialized from this data:
+
+```json
+{
+  "limit": 100,
+  "offset": 200,
+  "total": 10553,
+  "items": [
+    {"id": "49824073-979f-4814-be10-5ea416ee1c2f", username": "john_doe"},
+    ...
+  ]
+}
+```
+
+## Capture additional data
+
+A second common usecase for flatten is to collect all remaining data in a struct
+into a hashmap:
+
+```rust
+
+#[derive(Serialize, Deserialize, Debug)]
+struct Object {
+    id: String,
+    #[serde(rename = "type")]
+    ty: String,
+    #[serde(flatten)]
+    extra: HashMap<String, String>,
+}
+```
+
+This way additional data in an object can be collected into the `extra` hash map
+for later processing.

_src/field-attrs.md

@@ -17,6 +17,17 @@
   `default = "empty_value"` would invoke `empty_value()` and `default =
   "SomeTrait::some_default"` would invoke `SomeTrait::some_default()`.
 
+- #### `#[serde(flatten)]`
+
+  Flatten the contents of this field into the container it's defined in.
+
+  This removes one level of structure in a map or a value that serializes into
+  a map.  Structs are automatically converted into maps when flattening is
+  used.  This can for instance be used to capture the remaining fields in a
+  JSON object into a hash map or to move common keys into a separate object.
+
+  This feature currently cannot be used with internally or untagged enums.
+
 - ##### `#[serde(skip)]`
 
   Skip this field: do not serialize or deserialize it.