Add options `blank_lines_{lower|upper}_bound` to `Configurations.md`

[rust.git] / Configurations.md

diff --git a/Configurations.md b/Configurations.md
index 76589314e03c3d56a34af599688b8be63204b1b6..37e6fa0a998bf2e9dfc698a5b4125fae8fa382f4 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,6 +24,7 @@ Indent on expressions or items.
 
 - **Default value**: `"Block"`
 - **Possible values**: `"Block"`, `"Visual"`
+- **Stable**: No
 
 ### Array
 
@@ -218,7 +223,7 @@ 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,
@@ -248,6 +253,7 @@ Try to put attributes on the same line as fields and variants
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -293,6 +299,7 @@ Whether to use different formatting for items and expressions if they satisfy a
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -354,6 +361,7 @@ Where to put a binary operator when a binary expression goes multiline.
 
 - **Default value**: `"Front"`
 - **Possible values**: `"Front"`, `"Back"`
+- **Stable**: No
 
 #### `"Front"` (default):
 
@@ -385,44 +393,13 @@ 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();
-```
-
-#### `"Visual"`:
-
-```rust
-let lorem = ipsum.dolor()
-                 .sit()
-                 .amet()
-                 .consectetur()
-                 .adipiscing()
-                 .elit();
-```
-
-
-
 ## `combine_control_expr`
 
 Combine control expressions with function calls.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -530,6 +507,7 @@ 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.
 
@@ -552,6 +530,7 @@ Replace strings of _ wildcards by a single .. in tuple patterns
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -571,6 +550,7 @@ Brace style for control flow constructs
 
 - **Default value**: `"AlwaysSameLine"`
 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
+- **Stable**: No
 
 #### `"AlwaysSameLine"` (default):
 
@@ -612,6 +592,7 @@ Don't reformat anything
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 ## `error_on_line_overflow`
 
@@ -619,6 +600,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 +610,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).
 
@@ -636,7 +619,8 @@ See also [`comment_width`](#comment_width).
 Argument density in functions
 
 - **Default value**: `"Tall"`
-- **Possible values**: `"Compressed"`, `"CompressedIfEmpty"`, `"Tall"`, `"Vertical"`
+- **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
+- **Stable**: No
 
 #### `"Tall"` (default):
 
@@ -696,35 +680,6 @@ trait Lorem {
 }
 ```
 
-#### `"CompressedIfEmpty"`:
-
-```rust
-trait Lorem {
-    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,
-    ) {
-        // body
-    }
-}
-```
-
 #### `"Vertical"`:
 
 ```rust
@@ -768,6 +723,7 @@ Brace style for items
 
 - **Default value**: `"SameLineWhere"`
 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
+- **Stable**: No
 
 ### Functions
 
@@ -874,18 +830,20 @@ struct Dolor<T>
 ```
 
 
+## `empty_item_single_line`
 
-## `fn_empty_single_line`
-
-Put empty-body functions on a single line
+Put empty-body functions and impls on a single line
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
 ```rust
 fn lorem() {}
+
+impl Lorem {}
 ```
 
 #### `false`:
@@ -893,9 +851,12 @@ fn lorem() {}
 ```rust
 fn lorem() {
 }
+
+impl Lorem {
+}
 ```
 
-See also [`control_brace_style`](#control_brace_style).
+See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
 
 
 ## `fn_single_line`
@@ -904,6 +865,7 @@ Put single-expression functions on a single line
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -931,12 +893,45 @@ fn lorem() -> usize {
 
 See also [`control_brace_style`](#control_brace_style).
 
+
+## `where_single_line`
+
+To force single line where layout
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `false` (default):
+
+```rust
+impl<T> Lorem for T
+where
+    Option<T>: Ipsum,
+{
+    ...
+}
+```
+
+#### `true`:
+
+```rust
+impl<T> Lorem for T
+where Option<T>: Ipsum {
+    ...
+}
+```
+
+See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
+
+
 ## `force_explicit_abi`
 
 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.
 
@@ -962,6 +957,7 @@ Format string literals where necessary
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -985,6 +981,7 @@ Use tab characters for indentation, spaces for alignment
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `false` (default):
 
@@ -1004,28 +1001,6 @@ fn lorem() -> usize {
 
 See also: [`tab_spaces`](#tab_spaces).
 
-## `impl_empty_single_line`
-
-Put empty-body implementations on a single line
-
-- **Default value**: `true`
-- **Possible values**: `true`, `false`
-
-#### `true` (default):
-
-```rust
-impl Lorem {}
-```
-
-#### `false`:
-
-```rust
-impl Lorem {
-}
-```
-
-See also [`brace_style`](#brace_style).
-
 
 ## `imports_indent`
 
@@ -1033,6 +1008,7 @@ Indent style of imports
 
 - **Default Value**: `"Visual"`
 - **Possible values**: `"Block"`, `"Visual"`
+- **Stable**: No
 
 #### `"Visual"` (default):
 
@@ -1060,6 +1036,7 @@ Item layout inside a imports block
 
 - **Default value**: "Mixed"
 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
+- **Stable**: No
 
 #### `"Mixed"` (default):
 
@@ -1115,6 +1092,7 @@ 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):
 
@@ -1138,7 +1116,7 @@ match lorem {
 }
 ```
 
-See also: [`trailing_comma`](#trailing_comma), [`wrap_match_arms`](#wrap_match_arms).
+See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
 
 ## `max_width`
 
@@ -1146,6 +1124,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).
 
@@ -1155,6 +1134,7 @@ Merge multiple derives into a single one.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `true` (default):
 
@@ -1178,6 +1158,7 @@ Force multiline closure and match arm bodies to be wrapped in a block
 
 - **Default value**: `false`
 - **Possible values**: `false`, `true`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1223,6 +1204,7 @@ Unix or Windows line endings
 
 - **Default value**: `"Unix"`
 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
+- **Stable**: Yes
 
 ## `normalize_comments`
 
@@ -1230,6 +1212,7 @@ Convert /* */ comments to // comments where possible
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `false` (default):
 
@@ -1257,6 +1240,7 @@ Reorder lists of names in import statements alphabetically
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1278,6 +1262,7 @@ Reorder import statements alphabetically
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1305,6 +1290,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`.
 
@@ -1340,6 +1326,7 @@ Reorder `extern crate` statements alphabetically
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -1367,6 +1354,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`.
 
@@ -1402,6 +1390,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
@@ -1415,6 +1404,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
@@ -1429,6 +1419,7 @@ Don't reformat out of line modules
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 ## `space_after_colon`
 
@@ -1436,6 +1427,7 @@ Leave a space after the colon.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -1467,6 +1459,7 @@ Leave a space before the colon.
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1498,6 +1491,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):
 
@@ -1519,14 +1513,13 @@ struct Foo {
 }
 ```
 
-```
-
 ## `spaces_around_ranges`
 
 Put spaces around the .. and ... range operators
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1542,81 +1535,53 @@ let lorem = 0 .. 10;
 
 ## `spaces_within_parens_and_brackets`
 
-Put spaces within non-empty generic arguments
+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) {
     // body
 }
-```
-
-#### `true`:
-
-```rust
-fn lorem< T: Eq >(t: T) {
-    // body
-}
-```
-
-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
-
-- **Default value**: `false`
-- **Possible values**: `true`, `false`
-
-#### `false` (default):
-
-```rust
+// non-empty parentheses
 fn lorem<T: Eq>(t: T) {
     let lorem = (ipsum, dolor);
 }
+
+// non-empty square brackets
+let lorem: [usize; 2] = [ipsum, dolor];
 ```
 
 #### `true`:
 
 ```rust
+// generic arguments
+fn lorem< T: Eq >(t: T) {
+    // body
+}
+
+// non-empty parentheses
 fn lorem<T: Eq>( t: T ) {
     let lorem = ( 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):
-
-```rust
-let lorem: [usize; 2] = [ipsum, dolor];
-```
-
-#### `true`:
-
-```rust
+// non-empty square brackets
 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):
 
@@ -1642,6 +1607,7 @@ Number of spaces per tab
 
 - **Default value**: `4`
 - **Possible values**: any positive integer
+- **Stable**: Yes
 
 #### `4` (default):
 
@@ -1674,6 +1640,7 @@ How to handle trailing commas for lists
 
 - **Default value**: `"Vertical"`
 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
+- **Stable**: No
 
 #### `"Vertical"` (default):
 
@@ -1725,6 +1692,7 @@ Add trailing semicolon after break, continue and return
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 ```rust
@@ -1746,6 +1714,7 @@ Determines if `+` or `=` are wrapped in spaces in the punctuation of types
 
 - **Default value**: `"Wide"`
 - **Possible values**: `"Compressed"`, `"Wide"`
+- **Stable**: No
 
 #### `"Wide"` (default):
 
@@ -1769,6 +1738,7 @@ Replace uses of the try! macro by the ? shorthand
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1789,6 +1759,7 @@ Break comments to fit on the line
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
+- **Stable**: Yes
 
 #### `false` (default):
 
@@ -1806,12 +1777,13 @@ Break comments to fit on the line
 // commodo consequat.
 ```
 
-## `wrap_match_arms`
+## `match_arm_blocks`
 
 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
+- **Stable**: No
 
 #### `true` (default):
 
@@ -1842,3 +1814,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");
+}
+```