Merge pull request #263 from rylev/cleanup

Add more consistent headings and add a migration section to reserving-syntax

Author: ehuss

src/rust-2021/disjoint-capture-in-closures.md

@@ -28,7 +28,18 @@ Starting in Rust 2021, closures captures are more precise. Typically they will o
 
 Disjoint capture was proposed as part of [RFC 2229](https://github.com/rust-lang/rfcs/blob/master/text/2229-capture-disjoint-fields.md) and the RFC contains details about the motivation.
 
-## Migrating to Rust 2021
+## Migration
+
+As a part of the 2021 edition a migration lint, `rust_2021_incompatible_closure_captures`, has been added in order to aid in automatic migration of Rust 2018 codebases to Rust 2021.
+
+In order to have `rustfix` migrate your code to be Rust 2021 Edition compatible, run:
+
+```sh
+cargo fix --edition
+```
+
+Below is an examination of how to manually migrate code to use closure captures that are compatible with Rust 2021 should the automatic migration fail 
+or you would like to better understand how the migration works.
 
 Changing the variables captured by a closure can cause programs to change behavior or to stop compiling in two cases:
 

src/rust-2021/or-patterns-macro-rules.md

@@ -34,7 +34,7 @@ It's important to remember that editions are _per crate_, so the only relevant e
 of the crate where the macro is defined. The edition of the crate where the macro is used does not 
 change how the macro works.
 
-## Migration to Rust 2021
+## Migration 
 
 A lint, `rust_2021_incompatible_or_patterns`, gets triggered whenever there is a use `$_:pat` which
 will change meaning in Rust 2021. 

src/rust-2021/prelude.md

@@ -32,7 +32,7 @@ It's identical to the current one, except for three new additions:
 
 The tracking issue [can be found here](https://github.com/rust-lang/rust/issues/85684).
 
-## Migration to Rust 2021
+## Migration 
 
 As a part of the 2021 edition a migration lint, `rust_2021_prelude_collisions`, has been added in order to aid in automatic migration of Rust 2018 codebases to Rust 2021.
 

src/rust-2021/reserving-syntax.md

@@ -50,3 +50,36 @@ committed to any of them yet):
 - `c""` or `z""` for null-terminated C strings.
 
 [10]: https://github.com/rust-lang/rfcs/pull/3101
+
+
+## Migration 
+
+As a part of the 2021 edition a migration lint, `rust_2021_prefixes_incompatible_syntax`, has been added in order to aid in automatic migration of Rust 2018 codebases to Rust 2021.
+
+In order to have `rustfix` migrate your code to be Rust 2021 Edition compatible, run:
+
+```sh
+cargo fix --edition
+```
+
+Should you want or need to manually migrate your code, migration is fairly straight-forward.
+
+Let's say you have a macro that is defined like so:
+
+```rust
+macro_rules! my_macro {
+    ($a:tt $b:tt) => {};
+}
+```
+
+In Rust 2015 and 2018 it's legal for this macro to be called like so with no space between the first token tree and the second:
+
+```rust,ignore
+my_macro!(z"hey");
+```
+
+This `z` prefix is no longer allowed in Rust 2021, so in order to call this macro, you must add a space after the prefix like so:
+
+```rust,ignore
+my_macro!(z "hey");
+```