Update to the latest libsyntax changes

[rust.git] / Configurations.md

diff --git a/Configurations.md b/Configurations.md
index b02514c965b843f0d04cfe86fd2f4913a7a1f7dc..5a914a0d61039aed7ea010995c8a6e25053f12b1 100644 (file)
--- a/Configurations.md
+++ b/Configurations.md
@@ -9,6 +9,10 @@ indent_style = "Block"
 reorder_imported_names = true
 ```
 
+Each configuration option is either stable or unstable.
+Stable options can be used directly, while unstable options are opt-in.
+To enable unstable options, set `unstable_features = true` in `rustfmt.toml` or pass `--unstable-options` to rustfmt.
+
 # Configuration Options
 
 Below you find a detailed visual guide on all the supported configuration options of rustfmt:
@@ -20,33 +24,38 @@ Indent on expressions or items.
 
 - **Default value**: `"Block"`
 - **Possible values**: `"Block"`, `"Visual"`
+- **Stable**: No
 
 ### Array
 
 #### `"Block"` (default):
 
 ```rust
-let lorem = vec![
-    "ipsum",
-    "dolor",
-    "sit",
-    "amet",
-    "consectetur",
-    "adipiscing",
-    "elit",
-];
+fn main() {
+    let lorem = vec![
+        "ipsum",
+        "dolor",
+        "sit",
+        "amet",
+        "consectetur",
+        "adipiscing",
+        "elit",
+    ];
+}
 ```
 
 #### `"Visual"`:
 
 ```rust
-let lorem = vec!["ipsum",
-                 "dolor",
-                 "sit",
-                 "amet",
-                 "consectetur",
-                 "adipiscing",
-                 "elit"];
+fn main() {
+    let lorem = vec!["ipsum",
+                     "dolor",
+                     "sit",
+                     "amet",
+                     "consectetur",
+                     "adipiscing",
+                     "elit"];
+}
 ```
 
 ### Control flow
@@ -119,29 +128,33 @@ fn lorem(ipsum: usize,
 #### `"Block"` (default):
 
 ```rust
-lorem(
-    "lorem",
-    "ipsum",
-    "dolor",
-    "sit",
-    "amet",
-    "consectetur",
-    "adipiscing",
-    "elit",
-);
+fn main() {
+    lorem(
+        "lorem",
+        "ipsum",
+        "dolor",
+        "sit",
+        "amet",
+        "consectetur",
+        "adipiscing",
+        "elit",
+    );
+}
 ```
 
 #### `"Visual"`:
 
 ```rust
-lorem("lorem",
-      "ipsum",
-      "dolor",
-      "sit",
-      "amet",
-      "consectetur",
-      "adipiscing",
-      "elit");
+fn main() {
+    lorem("lorem",
+          "ipsum",
+          "dolor",
+          "sit",
+          "amet",
+          "consectetur",
+          "adipiscing",
+          "elit");
+}
 ```
 
 ### Generics
@@ -156,7 +169,7 @@ fn lorem<
     Amet: Eq = usize,
     Adipiscing: Eq = usize,
     Consectetur: Eq = usize,
-    Elit: Eq = usize
+    Elit: Eq = usize,
 >(
     ipsum: Ipsum,
     dolor: Dolor,
@@ -179,15 +192,15 @@ fn lorem<Ipsum: Eq = usize,
          Amet: Eq = usize,
          Adipiscing: Eq = usize,
          Consectetur: Eq = usize,
-         Elit: Eq = usize>
-    (ipsum: Ipsum,
-     dolor: Dolor,
-     sit: Sit,
-     amet: Amet,
-     adipiscing: Adipiscing,
-     consectetur: Consectetur,
-     elit: Elit)
-     -> T {
+         Elit: Eq = usize>(
+    ipsum: Ipsum,
+    dolor: Dolor,
+    sit: Sit,
+    amet: Amet,
+    adipiscing: Adipiscing,
+    consectetur: Consectetur,
+    elit: Elit)
+    -> T {
     // body
 }
 ```
@@ -197,17 +210,21 @@ fn lorem<Ipsum: Eq = usize,
 #### `"Block"` (default):
 
 ```rust
-let lorem = Lorem {
-    ipsum: dolor,
-    sit: amet,
-};
+fn main() {
+    let lorem = Lorem {
+        ipsum: dolor,
+        sit: amet,
+    };
+}
 ```
 
 #### `"Visual"`:
 
 ```rust
-let lorem = Lorem { ipsum: dolor,
-                    sit: amet, };
+fn main() {
+    let lorem = Lorem { ipsum: dolor,
+                        sit: amet, };
+}
 ```
 
 See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](#indent_style).
@@ -218,11 +235,11 @@ See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](
 
 ```rust
 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
-where 
+where
     Ipsum: Eq,
     Dolor: Eq,
     Sit: Eq,
-    Amet: Eq
+    Amet: Eq,
 {
     // body
 }
@@ -241,58 +258,13 @@ fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
 }
 ```
 
-
-## `same_line_attributes`
-
-Try to put attributes on the same line as fields and variants
-
-- **Default value**: `true`
-- **Possible values**: `true`, `false`
-
-#### `true` (default):
-
-```rust
-struct Lorem {
-    #[serde(rename = "Ipsum")] ipsum: usize,
-    #[serde(rename = "Dolor")] dolor: usize,
-    #[serde(rename = "Amet")] amet: usize,
-}
-
-enum Lorem {
-    #[serde(skip_serializing)] Ipsum,
-    #[serde(skip_serializing)] Dolor,
-    #[serde(skip_serializing)] Amet,
-}
-```
-
-#### `false`:
-
-```rust
-struct Lorem {
-    #[serde(rename = "Ipsum")]
-    ipsum: usize,
-    #[serde(rename = "Dolor")]
-    dolor: usize,
-    #[serde(rename = "Amet")]
-    amet: usize,
-}
-
-enum Lorem {
-    #[serde(skip_serializing)]
-    Ipsum,
-    #[serde(skip_serializing)]
-    Dolor,
-    #[serde(skip_serializing)]
-    Amet,
-}
-```
-
 ## `use_small_heuristics`
 
 Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -314,7 +286,11 @@ fn main() {
         "adipiscing",
     );
 
-    let lorem = Lorem { ipsum: dolor, sit: amet };
+    let lorem = Lorem {
+        ipsum: dolor,
+        sit: amet,
+    };
+    let lorem = Lorem { ipsum: dolor };
 
     let lorem = if ipsum { dolor } else { sit };
 }
@@ -354,75 +330,45 @@ Where to put a binary operator when a binary expression goes multiline.
 
 - **Default value**: `"Front"`
 - **Possible values**: `"Front"`, `"Back"`
+- **Stable**: No
 
 #### `"Front"` (default):
 
 ```rust
-let or = foo
-    || bar
-    || foobar;
+fn main() {
+    let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo
+        || barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 
-let sum = 1234
-    + 5678
-    + 910;
+    let sum = 123456789012345678901234567890 + 123456789012345678901234567890
+        + 123456789012345678901234567890;
 
-let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
-    ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
+    let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+        ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
+}
 ```
 
 #### `"Back"`:
 
 ```rust
-let or = foo ||
-    bar ||
-    foobar;
-
-let sum = 1234 +
-    5678 +
-    910;
-
-let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
-    bbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
-```
-
-## `chain_indent`
-
-Indentation of chain
-
-- **Default value**: `"Block"`
-- **Possible values**: `"Block"`, `"Visual"`
-
-#### `"Block"` (default):
-
-```rust
-let lorem = ipsum
-    .dolor()
-    .sit()
-    .amet()
-    .consectetur()
-    .adipiscing()
-    .elit();
-```
+fn main() {
+    let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
+        barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 
-#### `"Visual"`:
+    let sum = 123456789012345678901234567890 + 123456789012345678901234567890 +
+        123456789012345678901234567890;
 
-```rust
-let lorem = ipsum.dolor()
-                 .sit()
-                 .amet()
-                 .consectetur()
-                 .adipiscing()
-                 .elit();
+    let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
+        bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
+}
 ```
 
-
-
 ## `combine_control_expr`
 
 Combine control expressions with function calls.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -530,15 +476,16 @@ Maximum length of comments. No effect unless`wrap_comments = true`.
 
 - **Default value**: `80`
 - **Possible values**: any positive integer
+- **Stable**: No
 
 **Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
 
-#### Comments shorter than `comment_width`:
+#### `80` (default; comments shorter than `comment_width`):
 ```rust
 // Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 ```
 
-#### Comments longer than `comment_width`:
+#### `60` (comments longer than `comment_width`):
 ```rust
 // Lorem ipsum dolor sit amet,
 // consectetur adipiscing elit.
@@ -552,17 +499,23 @@ Replace strings of _ wildcards by a single .. in tuple patterns
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
-let (lorem, ipsum, _, _) = (1, 2, 3, 4);
+fn main() {
+    let (lorem, ipsum, _, _) = (1, 2, 3, 4);
+    let (lorem, ipsum, ..) = (1, 2, 3, 4);
+}
 ```
 
 #### `true`:
 
 ```rust
-let (lorem, ipsum, ..) = (1, 2, 3, 4);
+fn main() {
+    let (lorem, ipsum, ..) = (1, 2, 3, 4);
+}
 ```
 
 ## `control_brace_style`
@@ -571,38 +524,45 @@ Brace style for control flow constructs
 
 - **Default value**: `"AlwaysSameLine"`
 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
+- **Stable**: No
 
 #### `"AlwaysSameLine"` (default):
 
 ```rust
-if lorem {
-    println!("ipsum!");
-} else {
-    println!("dolor!");
+fn main() {
+    if lorem {
+        println!("ipsum!");
+    } else {
+        println!("dolor!");
+    }
 }
 ```
 
 #### `"AlwaysNextLine"`:
 
 ```rust
-if lorem
-{
-    println!("ipsum!");
-}
-else
-{
-    println!("dolor!");
+fn main() {
+    if lorem
+    {
+        println!("ipsum!");
+    }
+    else
+    {
+        println!("dolor!");
+    }
 }
 ```
 
 #### `"ClosingNextLine"`:
 
 ```rust
-if lorem {
-    println!("ipsum!");
-}
-else {
-    println!("dolor!");
+fn main() {
+    if lorem {
+        println!("ipsum!");
+    }
+    else {
+        println!("dolor!");
+    }
 }
 ```
 
@@ -612,6 +572,7 @@ Don't reformat anything
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 ## `error_on_line_overflow`
 
@@ -619,6 +580,7 @@ Error if unable to get all lines within `max_width`
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 See also [`max_width`](#max_width).
 
@@ -628,6 +590,7 @@ Error if unable to get all comment lines within `comment_width`.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 See also [`comment_width`](#comment_width).
 
@@ -637,6 +600,7 @@ Argument density in functions
 
 - **Default value**: `"Tall"`
 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
+- **Stable**: No
 
 #### `"Tall"` (default):
 
@@ -700,33 +664,41 @@ trait Lorem {
 
 ```rust
 trait Lorem {
-    fn lorem(ipsum: Ipsum,
-             dolor: Dolor,
-             sit: Sit,
-             amet: Amet);
-
-    fn lorem(ipsum: Ipsum,
-             dolor: Dolor,
-             sit: Sit,
-             amet: Amet) {
+    fn lorem(
+        ipsum: Ipsum,
+        dolor: Dolor,
+        sit: Sit,
+        amet: Amet,
+    );
+
+    fn lorem(
+        ipsum: Ipsum,
+        dolor: Dolor,
+        sit: Sit,
+        amet: Amet,
+    ) {
         // body
     }
 
-    fn lorem(ipsum: Ipsum,
-             dolor: Dolor,
-             sit: Sit,
-             amet: Amet,
-             consectetur: Consectetur,
-             adipiscing: Adipiscing,
-             elit: Elit);
-
-    fn lorem(ipsum: Ipsum,
-             dolor: Dolor,
-             sit: Sit,
-             amet: Amet,
-             consectetur: Consectetur,
-             adipiscing: Adipiscing,
-             elit: Elit) {
+    fn lorem(
+        ipsum: Ipsum,
+        dolor: Dolor,
+        sit: Sit,
+        amet: Amet,
+        consectetur: Consectetur,
+        adipiscing: Adipiscing,
+        elit: Elit,
+    );
+
+    fn lorem(
+        ipsum: Ipsum,
+        dolor: Dolor,
+        sit: Sit,
+        amet: Amet,
+        consectetur: Consectetur,
+        adipiscing: Adipiscing,
+        elit: Elit,
+    ) {
         // body
     }
 }
@@ -739,6 +711,7 @@ Brace style for items
 
 - **Default value**: `"SameLineWhere"`
 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
+- **Stable**: No
 
 ### Functions
 
@@ -810,7 +783,8 @@ struct Lorem {
 }
 
 struct Dolor<T>
-    where T: Eq
+where
+    T: Eq,
 {
     sit: T,
 }
@@ -825,7 +799,8 @@ struct Lorem
 }
 
 struct Dolor<T>
-    where T: Eq
+where
+    T: Eq,
 {
     sit: T,
 }
@@ -839,7 +814,8 @@ struct Lorem {
 }
 
 struct Dolor<T>
-    where T: Eq {
+where
+    T: Eq, {
     sit: T,
 }
 ```
@@ -851,6 +827,7 @@ Put empty-body functions and impls on a single line
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -879,6 +856,7 @@ Put single-expression functions on a single line
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -913,6 +891,7 @@ To force single line where layout
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -921,7 +900,7 @@ impl<T> Lorem for T
 where
     Option<T>: Ipsum,
 {
-    ...
+    // body
 }
 ```
 
@@ -929,8 +908,9 @@ where
 
 ```rust
 impl<T> Lorem for T
-where Option<T>: Ipsum {
-    ...
+where Option<T>: Ipsum
+{
+    // body
 }
 ```
 
@@ -943,6 +923,7 @@ Always print the abi for extern items
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
 
@@ -968,19 +949,24 @@ Format string literals where necessary
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
-let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
+fn main() {
+    let lorem =
+        "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet consectetur adipiscing";
+}
 ```
 
 #### `true`:
 
 ```rust
-let lorem =
-    "ipsum dolor sit amet consectetur \
-     adipiscing elit lorem ipsum dolor sit";
+fn main() {
+    let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet \
+                 consectetur adipiscing";
+}
 ```
 
 See also [`max_width`](#max_width).
@@ -991,6 +977,7 @@ Use tab characters for indentation, spaces for alignment
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `false` (default):
 
@@ -1017,22 +1004,21 @@ Indent style of imports
 
 - **Default Value**: `"Visual"`
 - **Possible values**: `"Block"`, `"Visual"`
+- **Stable**: No
 
 #### `"Visual"` (default):
 
 ```rust
-use foo::{xxx,
-          yyy,
-          zzz};
+use foo::{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
+          zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz};
 ```
 
 #### `"Block"`:
 
 ```rust
 use foo::{
-    xxx,
-    yyy,
-    zzz,
+    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
+    zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz,
 };
 ```
 
@@ -1044,19 +1030,20 @@ Item layout inside a imports block
 
 - **Default value**: "Mixed"
 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
+- **Stable**: No
 
 #### `"Mixed"` (default):
 
 ```rust
-use foo::{xxx, yyy, zzz};
+use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
 
-use foo::{aaa, bbb, ccc,
-          ddd, eee, fff};
+use foo::{aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
+          eeeeeeeeeeeeeeeeee, ffffffffffffffffff};
 ```
 
 #### `"Horizontal"`:
 
-**Note**: This option forces to put everything on one line and may exceeds `max_width`.
+**Note**: This option forces all imports onto one line and may exceed `max_width`.
 
 ```rust
 use foo::{xxx, yyy, zzz};
@@ -1067,14 +1054,14 @@ use foo::{aaa, bbb, ccc, ddd, eee, fff};
 #### `"HorizontalVertical"`:
 
 ```rust
-use foo::{xxx, yyy, zzz};
+use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
 
-use foo::{aaa,
-          bbb,
-          ccc,
-          ddd,
-          eee,
-          fff};
+use foo::{aaaaaaaaaaaaaaaaaa,
+          bbbbbbbbbbbbbbbbbb,
+          cccccccccccccccccc,
+          dddddddddddddddddd,
+          eeeeeeeeeeeeeeeeee,
+          ffffffffffffffffff};
 ```
 
 #### `"Vertical"`:
@@ -1099,26 +1086,31 @@ Put a trailing comma after a block based match arm (non-block arms are not affec
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
-match lorem {
-    Lorem::Ipsum => {
-        println!("ipsum");
+fn main() {
+    match lorem {
+        Lorem::Ipsum => {
+            println!("ipsum");
+        }
+        Lorem::Dolor => println!("dolor"),
     }
-    Lorem::Dolor => println!("dolor"),
 }
 ```
 
 #### `true`:
 
 ```rust
-match lorem {
-    Lorem::Ipsum => {
-        println!("ipsum");
-    },
-    Lorem::Dolor => println!("dolor"),
+fn main() {
+    match lorem {
+        Lorem::Ipsum => {
+            println!("ipsum");
+        },
+        Lorem::Dolor => println!("dolor"),
+    }
 }
 ```
 
@@ -1130,6 +1122,7 @@ Maximum width of each line
 
 - **Default value**: `100`
 - **Possible values**: any positive integer
+- **Stable**: Yes
 
 See also [`error_on_line_overflow`](#error_on_line_overflow).
 
@@ -1139,6 +1132,7 @@ Merge multiple derives into a single one.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `true` (default):
 
@@ -1162,41 +1156,45 @@ Force multiline closure and match arm bodies to be wrapped in a block
 
 - **Default value**: `false`
 - **Possible values**: `false`, `true`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
-result.and_then(|maybe_value| match maybe_value {
-    None => ...,
-    Some(value) => ...,
-})
+fn main() {
+    result.and_then(|maybe_value| match maybe_value {
+        None => foo(),
+        Some(value) => bar(),
+    });
 
-match lorem {
-    None => if ipsum {
-        println!("Hello World");
-    },
-    Some(dolor) => ...,
+    match lorem {
+        None => if ipsum {
+            println!("Hello World");
+        },
+        Some(dolor) => foo(),
+    }
 }
 ```
 
 #### `true`:
 
 ```rust
+fn main() {
+    result.and_then(|maybe_value| {
+        match maybe_value {
+            None => foo(),
+            Some(value) => bar(),
+        }
+    });
 
-result.and_then(|maybe_value| {
-    match maybe_value {
-        None => ...,
-        Some(value) => ...,
-    }
-})
-
-match lorem {
-    None => {
-        if ipsum {
-            println!("Hello World");
+    match lorem {
+        None => {
+            if ipsum {
+                println!("Hello World");
+            }
         }
+        Some(dolor) => foo(),
     }
-    Some(dolor) => ...,
 }
 ```
 
@@ -1207,6 +1205,7 @@ Unix or Windows line endings
 
 - **Default value**: `"Unix"`
 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
+- **Stable**: Yes
 
 ## `normalize_comments`
 
@@ -1214,6 +1213,7 @@ Convert /* */ comments to // comments where possible
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `false` (default):
 
@@ -1241,6 +1241,7 @@ Reorder lists of names in import statements alphabetically
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1262,6 +1263,7 @@ Reorder import statements alphabetically
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1289,6 +1291,7 @@ Reorder import statements in group
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
 
@@ -1324,6 +1327,7 @@ Reorder `extern crate` statements alphabetically
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -1351,6 +1355,7 @@ Reorder `extern crate` statements in group
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
 
@@ -1386,6 +1391,7 @@ Report `TODO` items in comments.
 
 - **Default value**: `"Never"`
 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
+- **Stable**: No
 
 Warns about any comments containing `TODO` in them when set to `"Always"`. If
 it contains a `#X` (with `X` being a number) in parentheses following the
@@ -1399,6 +1405,7 @@ Report `FIXME` items in comments.
 
 - **Default value**: `"Never"`
 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
+- **Stable**: No
 
 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
 it contains a `#X` (with `X` being a number) in parentheses following the
@@ -1413,6 +1420,7 @@ Don't reformat out of line modules
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 ## `space_after_colon`
 
@@ -1420,6 +1428,7 @@ Leave a space after the colon.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -1451,6 +1460,7 @@ Leave a space before the colon.
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1482,6 +1492,7 @@ The maximum diff of width between struct fields to be aligned with each other.
 
 - **Default value** : 0
 - **Possible values**: any positive integer
+- **Stable**: No
 
 #### `0` (default):
 
@@ -1503,104 +1514,115 @@ struct Foo {
 }
 ```
 
-```
-
 ## `spaces_around_ranges`
 
-Put spaces around the .. and ... range operators
+Put spaces around the .., ..=, and ... range operators
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
-let lorem = 0..10;
-```
-
-#### `true`:
-
-```rust
-let lorem = 0 .. 10;
-```
-
-## `spaces_within_parens_and_brackets`
-
-Put spaces within non-empty generic arguments
+fn main() {
+    let lorem = 0..10;
+    let ipsum = 0..=10;
 
-- **Default value**: `false`
-- **Possible values**: `true`, `false`
+    match lorem {
+        1..5 => foo(),
+        _ => bar,
+    }
 
-#### `false` (default):
+    match lorem {
+        1..=5 => foo(),
+        _ => bar,
+    }
 
-```rust
-fn lorem<T: Eq>(t: T) {
-    // body
+    match lorem {
+        1...5 => foo(),
+        _ => bar,
+    }
 }
 ```
 
 #### `true`:
 
 ```rust
-fn lorem< T: Eq >(t: T) {
-    // body
+fn main() {
+    let lorem = 0 .. 10;
+    let ipsum = 0 ..= 10;
+
+    match lorem {
+        1 .. 5 => foo(),
+        _ => bar,
+    }
+
+    match lorem {
+        1 ..= 5 => foo(),
+        _ => bar,
+    }
+
+    match lorem {
+        1 ... 5 => foo(),
+        _ => bar,
+    }
 }
 ```
 
-See also: [`spaces_within_parens_and_brackets`](#spaces_within_parens_and_brackets), [`spaces_within_parens_and_brackets`](#spaces_within_parens_and_brackets).
-
 ## `spaces_within_parens_and_brackets`
 
-Put spaces within non-empty parentheses
+Put spaces within non-empty generic arguments, parentheses, and square brackets
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
+// generic arguments
 fn lorem<T: Eq>(t: T) {
-    let lorem = (ipsum, dolor);
+    // body
 }
-```
 
-#### `true`:
+// non-empty parentheses
+fn lorem<T: Eq>(t: T) {
+    let lorem = (ipsum, dolor);
+}
 
-```rust
-fn lorem<T: Eq>( t: T ) {
-    let lorem = ( ipsum, dolor );
+// non-empty square brackets
+fn lorem<T: Eq>(t: T) {
+    let lorem: [usize; 2] = [ipsum, dolor];
 }
 ```
 
-See also: [`spaces_within_parens_and_brackets`](#spaces_within_parens_and_brackets), [`spaces_within_parens_and_brackets`](#spaces_within_parens_and_brackets).
-
-## `spaces_within_parens_and_brackets`
-
-Put spaces within non-empty square brackets
-
-- **Default value**: `false`
-- **Possible values**: `true`, `false`
-
-#### `false` (default):
+#### `true`:
 
 ```rust
-let lorem: [usize; 2] = [ipsum, dolor];
-```
+// generic arguments
+fn lorem< T: Eq >( t: T ) {
+    // body
+}
 
-#### `true`:
+// non-empty parentheses
+fn lorem< T: Eq >( t: T ) {
+    let lorem = ( ipsum, dolor );
+}
 
-```rust
-let lorem: [ usize; 2 ] = [ ipsum, dolor ];
+// non-empty square brackets
+fn lorem< T: Eq >( t: T ) {
+    let lorem: [ usize; 2 ] = [ ipsum, dolor ];
+}
 ```
 
-See also: [`spaces_within_parens_and_brackets`](#spaces_within_parens_and_brackets), [`spaces_within_parens_and_brackets`](#spaces_within_parens_and_brackets).
-
 ## `struct_lit_single_line`
 
 Put small struct literals on a single line
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -1611,10 +1633,12 @@ let lorem = Lorem { ipsum: dolor, sit: amet };
 #### `false`:
 
 ```rust
-let lorem = Lorem {
-    ipsum: dolor,
-    sit: amet,
-};
+fn main() {
+    let lorem = Lorem {
+        ipsum: dolor,
+        sit: amet,
+    };
+}
 ```
 
 See also: [`indent_style`](#indent_style).
@@ -1626,6 +1650,7 @@ Number of spaces per tab
 
 - **Default value**: `4`
 - **Possible values**: any positive integer
+- **Stable**: Yes
 
 #### `4` (default):
 
@@ -1633,7 +1658,7 @@ Number of spaces per tab
 fn lorem() {
     let ipsum = dolor();
     let sit = vec![
-        "amet consectetur adipiscing elit."
+        "amet consectetur adipiscing elit amet consectetur adipiscing elit amet consectetur.",
     ];
 }
 ```
@@ -1644,7 +1669,7 @@ fn lorem() {
 fn lorem() {
   let ipsum = dolor();
   let sit = vec![
-    "amet consectetur adipiscing elit."
+    "amet consectetur adipiscing elit amet consectetur adipiscing elit amet consectetur.",
   ];
 }
 ```
@@ -1658,47 +1683,54 @@ How to handle trailing commas for lists
 
 - **Default value**: `"Vertical"`
 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
+- **Stable**: No
 
 #### `"Vertical"` (default):
 
 ```rust
-let Lorem { ipsum, dolor, sit } = amet;
-let Lorem {
-    ipsum,
-    dolor,
-    sit,
-    amet,
-    consectetur,
-    adipiscing,
-} = elit;
+fn main() {
+    let Lorem { ipsum, dolor, sit } = amet;
+    let Lorem {
+        ipsum,
+        dolor,
+        sit,
+        amet,
+        consectetur,
+        adipiscing,
+    } = elit;
+}
 ```
 
 #### `"Always"`:
 
 ```rust
-let Lorem { ipsum, dolor, sit, } = amet;
-let Lorem {
-    ipsum,
-    dolor,
-    sit,
-    amet,
-    consectetur,
-    adipiscing,
-} = elit;
+fn main() {
+    let Lorem { ipsum, dolor, sit, } = amet;
+    let Lorem {
+        ipsum,
+        dolor,
+        sit,
+        amet,
+        consectetur,
+        adipiscing,
+    } = elit;
+}
 ```
 
 #### `"Never"`:
 
 ```rust
-let Lorem { ipsum, dolor, sit } = amet;
-let Lorem {
-    ipsum,
-    dolor,
-    sit,
-    amet,
-    consectetur,
-    adipiscing
-} = elit;
+fn main() {
+    let Lorem { ipsum, dolor, sit } = amet;
+    let Lorem {
+        ipsum,
+        dolor,
+        sit,
+        amet,
+        consectetur,
+        adipiscing
+    } = elit;
+}
 ```
 
 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
@@ -1709,6 +1741,7 @@ Add trailing semicolon after break, continue and return
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 ```rust
@@ -1730,12 +1763,13 @@ Determines if `+` or `=` are wrapped in spaces in the punctuation of types
 
 - **Default value**: `"Wide"`
 - **Possible values**: `"Compressed"`, `"Wide"`
+- **Stable**: No
 
 #### `"Wide"` (default):
 
 ```rust
 fn lorem<Ipsum: Dolor + Sit = Amet>() {
-       // body
+    // body
 }
 ```
 
@@ -1743,7 +1777,7 @@ fn lorem<Ipsum: Dolor + Sit = Amet>() {
 
 ```rust
 fn lorem<Ipsum: Dolor+Sit=Amet>() {
-       // body
+    // body
 }
 ```
 
@@ -1753,17 +1787,22 @@ Replace uses of the try! macro by the ? shorthand
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
 ```rust
-let lorem = try!(ipsum.map(|dolor|dolor.sit()));
+fn main() {
+    let lorem = try!(ipsum.map(|dolor| dolor.sit()));
+}
 ```
 
 #### `true`:
 
 ```rust
-let lorem = ipsum.map(|dolor| dolor.sit())?;
+fn main() {
+    let lorem = ipsum.map(|dolor| dolor.sit())?;
+}
 ```
 
 
@@ -1773,6 +1812,7 @@ Break comments to fit on the line
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `false` (default):
 
@@ -1796,25 +1836,30 @@ Wrap the body of arms in blocks when it does not fit on the same line with the p
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
 ```rust
-match lorem {
-    true => {
-        foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
+fn main() {
+    match lorem {
+        true => {
+            foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
+        }
+        false => println!("{}", sit),
     }
-    false => println!("{}", sit),
 }
 ```
 
 #### `false`:
 
 ```rust
-match lorem {
-    true =>
-        foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
-    false => println!("{}", sit),
+fn main() {
+    match lorem {
+        true =>
+            foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
+        false => println!("{}", sit),
+    }
 }
 ```
 
@@ -1826,3 +1871,98 @@ What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff,
 
 - **Default value**: `"Overwrite"`
 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
+- **Stable**: No
+
+## `blank_lines_upper_bound`
+
+Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
+lines are found, they are trimmed down to match this integer.
+
+- **Default value**: `1`
+- **Possible values**: *unsigned integer*
+- **Stable**: No
+
+### Example
+Original Code:
+
+```rust
+fn foo() {
+    println!("a");
+}
+
+
+
+fn bar() {
+    println!("b");
+
+
+    println!("c");
+}
+```
+
+#### `1` (default):
+```rust
+fn foo() {
+    println!("a");
+}
+
+fn bar() {
+    println!("b");
+
+    println!("c");
+}
+```
+
+#### `2` (default):
+```rust
+fn foo() {
+    println!("a");
+}
+
+
+fn bar() {
+    println!("b");
+
+
+    println!("c");
+}
+```
+
+See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
+
+## `blank_lines_lower_bound`
+
+Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
+them, additional blank lines are inserted.
+
+- **Default value**: `0`
+- **Possible values**: *unsigned integer*
+- **Stable**: No
+
+### Example
+Original Code (rustfmt will not change it with the default value of `0`):
+
+```rust
+fn foo() {
+    println!("a");
+}
+fn bar() {
+    println!("b");
+    println!("c");
+}
+```
+
+#### `1`
+```rust
+fn foo() {
+
+    println!("a");
+}
+
+fn bar() {
+
+    println!("b");
+
+    println!("c");
+}
+```