3 files changed, 374 insertions, 170 deletions

diff --git a/docs/user/assists.md b/docs/user/generated_assists.adoc
index 04387e3b0..580ab4358 100644
--- a/docs/user/assists.md
+++ b/docs/user/generated_assists.adoc
@@ -1,18 +1,17 @@
-# Assists
-
-Cursor position or selection is signified by `┃` character.
-
-
-## `add_custom_impl`
+[discrete]
+=== `add_custom_impl`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_custom_impl.rs#L14[add_custom_impl.rs]
 
 Adds impl block for derived trait.
 
+.Before
 ```rust
-// BEFORE
 #[derive(Deb┃ug, Display)]
 struct S;
+```
 
-// AFTER
+.After
+```rust
 #[derive(Display)]
 struct S;
 
@@ -21,18 +20,23 @@ impl Debug for S {
 }
 ```
 
-## `add_derive`
+
+[discrete]
+=== `add_derive`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_derive.rs#L9[add_derive.rs]
 
 Adds a new `#[derive()]` clause to a struct or enum.
 
+.Before
 ```rust
-// BEFORE
 struct Point {
     x: u32,
     y: u32,┃
 }
+```
 
-// AFTER
+.After
+```rust
 #[derive($0)]
 struct Point {
     x: u32,
@@ -40,31 +44,41 @@ struct Point {
 }
 ```
 
-## `add_explicit_type`
+
+[discrete]
+=== `add_explicit_type`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_explicit_type.rs#L9[add_explicit_type.rs]
 
 Specify type for a let binding.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     let x┃ = 92;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     let x: i32 = 92;
 }
 ```
 
-## `add_from_impl_for_enum`
+
+[discrete]
+=== `add_from_impl_for_enum`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs#L7[add_from_impl_for_enum.rs]
 
 Adds a From impl for an enum variant with one tuple field.
 
+.Before
 ```rust
-// BEFORE
 enum A { ┃One(u32) }
+```
 
-// AFTER
+.After
+```rust
 enum A { One(u32) }
 
 impl From<u32> for A {
@@ -74,20 +88,25 @@ impl From<u32> for A {
 }
 ```
 
-## `add_function`
+
+[discrete]
+=== `add_function`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_function.rs#L19[add_function.rs]
 
 Adds a stub function with a signature matching the function under the cursor.
 
+.Before
 ```rust
-// BEFORE
 struct Baz;
 fn baz() -> Baz { Baz }
 fn foo() {
     bar┃("", baz());
 }
 
+```
 
-// AFTER
+.After
+```rust
 struct Baz;
 fn baz() -> Baz { Baz }
 fn foo() {
@@ -100,33 +119,43 @@ fn bar(arg: &str, baz: Baz) {
 
 ```
 
-## `add_hash`
+
+[discrete]
+=== `add_hash`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L65[raw_string.rs]
 
 Adds a hash to a raw string literal.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     r#"Hello,┃ World!"#;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     r##"Hello, World!"##;
 }
 ```
 
-## `add_impl`
+
+[discrete]
+=== `add_impl`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_impl.rs#L6[add_impl.rs]
 
 Adds a new inherent impl for a type.
 
+.Before
 ```rust
-// BEFORE
 struct Ctx<T: Clone> {
     data: T,┃
 }
+```
 
-// AFTER
+.After
+```rust
 struct Ctx<T: Clone> {
     data: T,
 }
@@ -136,12 +165,15 @@ impl<T: Clone> Ctx<T> {
 }
 ```
 
-## `add_impl_default_members`
+
+[discrete]
+=== `add_impl_default_members`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_missing_impl_members.rs#L64[add_missing_impl_members.rs]
 
 Adds scaffold for overriding default impl members.
 
+.Before
 ```rust
-// BEFORE
 trait Trait {
     Type X;
     fn foo(&self);
@@ -153,8 +185,10 @@ impl Trait for () {
     fn foo(&self) {}┃
 
 }
+```
 
-// AFTER
+.After
+```rust
 trait Trait {
     Type X;
     fn foo(&self);
@@ -169,12 +203,15 @@ impl Trait for () {
 }
 ```
 
-## `add_impl_missing_members`
+
+[discrete]
+=== `add_impl_missing_members`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_missing_impl_members.rs#L24[add_missing_impl_members.rs]
 
 Adds scaffold for required impl members.
 
+.Before
 ```rust
-// BEFORE
 trait Trait<T> {
     Type X;
     fn foo(&self) -> T;
@@ -184,8 +221,10 @@ trait Trait<T> {
 impl Trait<u32> for () {┃
 
 }
+```
 
-// AFTER
+.After
+```rust
 trait Trait<T> {
     Type X;
     fn foo(&self) -> T;
@@ -200,17 +239,22 @@ impl Trait<u32> for () {
 }
 ```
 
-## `add_new`
+
+[discrete]
+=== `add_new`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_new.rs#L12[add_new.rs]
 
 Adds a new inherent impl for a type.
 
+.Before
 ```rust
-// BEFORE
 struct Ctx<T: Clone> {
      data: T,┃
 }
+```
 
-// AFTER
+.After
+```rust
 struct Ctx<T: Clone> {
      data: T,
 }
@@ -221,25 +265,33 @@ impl<T: Clone> Ctx<T> {
 
 ```
 
-## `add_turbo_fish`
+
+[discrete]
+=== `add_turbo_fish`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_turbo_fish.rs#L10[add_turbo_fish.rs]
 
 Adds `::<_>` to a call of a generic method or function.
 
+.Before
 ```rust
-// BEFORE
 fn make<T>() -> T { todo!() }
 fn main() {
     let x = make┃();
 }
+```
 
-// AFTER
+.After
+```rust
 fn make<T>() -> T { todo!() }
 fn main() {
     let x = make::<${0:_}>();
 }
 ```
 
-## `apply_demorgan`
+
+[discrete]
+=== `apply_demorgan`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/apply_demorgan.rs#L5[apply_demorgan.rs]
 
 Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
 This transforms expressions of the form `!l || !r` into `!(l && r)`.
@@ -247,29 +299,36 @@ This also works with `&&`. This assist can only be applied with the cursor
 on either `||` or `&&`, with both operands being a negation of some kind.
 This means something of the form `!x` or `x != y`.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     if x != 4 ||┃ !y {}
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     if !(x == 4 && y) {}
 }
 ```
 
-## `auto_import`
+
+[discrete]
+=== `auto_import`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/auto_import.rs#L18[auto_import.rs]
 
 If the name is unresolved, provides all possible imports for it.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     let map = HashMap┃::new();
 }
+```
 
-// AFTER
+.After
+```rust
 use std::collections::HashMap;
 
 fn main() {
@@ -277,12 +336,15 @@ fn main() {
 }
 ```
 
-## `change_lifetime_anon_to_named`
+
+[discrete]
+=== `change_lifetime_anon_to_named`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_lifetime_anon_to_named.rs#L9[change_lifetime_anon_to_named.rs]
 
 Change an anonymous lifetime to a named lifetime.
 
+.Before
 ```rust
-// BEFORE
 impl Cursor<'_┃> {
     fn node(self) -> &SyntaxNode {
         match self {
@@ -290,8 +352,10 @@ impl Cursor<'_┃> {
         }
     }
 }
+```
 
-// AFTER
+.After
+```rust
 impl<'a> Cursor<'a> {
     fn node(self) -> &SyntaxNode {
         match self {
@@ -301,44 +365,59 @@ impl<'a> Cursor<'a> {
 }
 ```
 
-## `change_return_type_to_result`
+
+[discrete]
+=== `change_return_type_to_result`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_return_type_to_result.rs#L8[change_return_type_to_result.rs]
 
 Change the function's return type to Result.
 
+.Before
 ```rust
-// BEFORE
 fn foo() -> i32┃ { 42i32 }
+```
 
-// AFTER
+.After
+```rust
 fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
 ```
 
-## `change_visibility`
+
+[discrete]
+=== `change_visibility`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_visibility.rs#L14[change_visibility.rs]
 
 Adds or changes existing visibility specifier.
 
+.Before
 ```rust
-// BEFORE
 ┃fn frobnicate() {}
+```
 
-// AFTER
+.After
+```rust
 pub(crate) fn frobnicate() {}
 ```
 
-## `convert_to_guarded_return`
+
+[discrete]
+=== `convert_to_guarded_return`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/early_return.rs#L21[early_return.rs]
 
 Replace a large conditional with a guarded return.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     ┃if cond {
         foo();
         bar();
     }
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     if !cond {
         return;
@@ -348,12 +427,15 @@ fn main() {
 }
 ```
 
-## `fill_match_arms`
+
+[discrete]
+=== `fill_match_arms`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/fill_match_arms.rs#L14[fill_match_arms.rs]
 
 Adds missing clauses to a `match` expression.
 
+.Before
 ```rust
-// BEFORE
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -361,8 +443,10 @@ fn handle(action: Action) {
         ┃
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -373,20 +457,25 @@ fn handle(action: Action) {
 }
 ```
 
-## `fix_visibility`
+
+[discrete]
+=== `fix_visibility`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/fix_visibility.rs#L13[fix_visibility.rs]
 
 Makes inaccessible item public.
 
+.Before
 ```rust
-// BEFORE
 mod m {
     fn frobnicate() {}
 }
 fn main() {
     m::frobnicate┃() {}
 }
+```
 
-// AFTER
+.After
+```rust
 mod m {
     $0pub(crate) fn frobnicate() {}
 }
@@ -395,154 +484,202 @@ fn main() {
 }
 ```
 
-## `flip_binexpr`
+
+[discrete]
+=== `flip_binexpr`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_binexpr.rs#L5[flip_binexpr.rs]
 
 Flips operands of a binary expression.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     let _ = 90 +┃ 2;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     let _ = 2 + 90;
 }
 ```
 
-## `flip_comma`
+
+[discrete]
+=== `flip_comma`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_comma.rs#L5[flip_comma.rs]
 
 Flips two comma-separated items.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     ((1, 2),┃ (3, 4));
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     ((3, 4), (1, 2));
 }
 ```
 
-## `flip_trait_bound`
+
+[discrete]
+=== `flip_trait_bound`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_trait_bound.rs#L9[flip_trait_bound.rs]
 
 Flips two trait bounds.
 
+.Before
 ```rust
-// BEFORE
 fn foo<T: Clone +┃ Copy>() { }
+```
 
-// AFTER
+.After
+```rust
 fn foo<T: Copy + Clone>() { }
 ```
 
-## `inline_local_variable`
+
+[discrete]
+=== `inline_local_variable`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/inline_local_variable.rs#L13[inline_local_variable.rs]
 
 Inlines local variable.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     let x┃ = 1 + 2;
     x * 4;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     (1 + 2) * 4;
 }
 ```
 
-## `introduce_variable`
+
+[discrete]
+=== `introduce_variable`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/introduce_variable.rs#L14[introduce_variable.rs]
 
 Extracts subexpression into a variable.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     ┃(1 + 2)┃ * 4;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     let $0var_name = (1 + 2);
     var_name * 4;
 }
 ```
 
-## `invert_if`
+
+[discrete]
+=== `invert_if`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/invert_if.rs#L12[invert_if.rs]
 
 Apply invert_if
 This transforms if expressions of the form `if !x {A} else {B}` into `if x {B} else {A}`
 This also works with `!=`. This assist can only be applied with the cursor
 on `if`.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     if┃ !y { A } else { B }
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     if y { B } else { A }
 }
 ```
 
-## `make_raw_string`
+
+[discrete]
+=== `make_raw_string`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L10[raw_string.rs]
 
 Adds `r#` to a plain string literal.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     "Hello,┃ World!";
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     r#"Hello, World!"#;
 }
 ```
 
-## `make_usual_string`
+
+[discrete]
+=== `make_usual_string`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L39[raw_string.rs]
 
 Turns a raw string into a plain string.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     r#"Hello,┃ "World!""#;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     "Hello, \"World!\"";
 }
 ```
 
-## `merge_imports`
+
+[discrete]
+=== `merge_imports`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/merge_imports.rs#L14[merge_imports.rs]
 
 Merges two imports with a common prefix.
 
+.Before
 ```rust
-// BEFORE
 use std::┃fmt::Formatter;
 use std::io;
+```
 
-// AFTER
+.After
+```rust
 use std::{fmt::Formatter, io};
 ```
 
-## `merge_match_arms`
+
+[discrete]
+=== `merge_match_arms`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/merge_match_arms.rs#L11[merge_match_arms.rs]
 
 Merges identical match arms.
 
+.Before
 ```rust
-// BEFORE
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -551,8 +688,10 @@ fn handle(action: Action) {
         Action::Stop => foo(),
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -562,12 +701,15 @@ fn handle(action: Action) {
 }
 ```
 
-## `move_arm_cond_to_match_guard`
+
+[discrete]
+=== `move_arm_cond_to_match_guard`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_guard.rs#L56[move_guard.rs]
 
 Moves if expression from match arm body into a guard.
 
+.Before
 ```rust
-// BEFORE
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -576,8 +718,10 @@ fn handle(action: Action) {
         _ => (),
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -588,28 +732,36 @@ fn handle(action: Action) {
 }
 ```
 
-## `move_bounds_to_where_clause`
+
+[discrete]
+=== `move_bounds_to_where_clause`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_bounds.rs#L10[move_bounds.rs]
 
 Moves inline type bounds to a where clause.
 
+.Before
 ```rust
-// BEFORE
 fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U {
     f(x)
 }
+```
 
-// AFTER
+.After
+```rust
 fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U {
     f(x)
 }
 ```
 
-## `move_guard_to_arm_body`
+
+[discrete]
+=== `move_guard_to_arm_body`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_guard.rs#L8[move_guard.rs]
 
 Moves match guard into match arm body.
 
+.Before
 ```rust
-// BEFORE
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -618,8 +770,10 @@ fn handle(action: Action) {
         _ => (),
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -630,75 +784,98 @@ fn handle(action: Action) {
 }
 ```
 
-## `remove_dbg`
+
+[discrete]
+=== `remove_dbg`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/remove_dbg.rs#L8[remove_dbg.rs]
 
 Removes `dbg!()` macro call.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     ┃dbg!(92);
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     92;
 }
 ```
 
-## `remove_hash`
+
+[discrete]
+=== `remove_hash`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L89[raw_string.rs]
 
 Removes a hash from a raw string literal.
 
+.Before
 ```rust
-// BEFORE
 fn main() {
     r#"Hello,┃ World!"#;
 }
+```
 
-// AFTER
+.After
+```rust
 fn main() {
     r"Hello, World!";
 }
 ```
 
-## `remove_mut`
+
+[discrete]
+=== `remove_mut`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/remove_mut.rs#L5[remove_mut.rs]
 
 Removes the `mut` keyword.
 
+.Before
 ```rust
-// BEFORE
 impl Walrus {
     fn feed(&mut┃ self, amount: u32) {}
 }
+```
 
-// AFTER
+.After
+```rust
 impl Walrus {
     fn feed(&self, amount: u32) {}
 }
 ```
 
-## `reorder_fields`
+
+[discrete]
+=== `reorder_fields`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/reorder_fields.rs#L10[reorder_fields.rs]
 
 Reorder the fields of record literals and record patterns in the same order as in
 the definition.
 
+.Before
 ```rust
-// BEFORE
 struct Foo {foo: i32, bar: i32};
 const test: Foo = ┃Foo {bar: 0, foo: 1}
+```
 
-// AFTER
+.After
+```rust
 struct Foo {foo: i32, bar: i32};
 const test: Foo = Foo {foo: 1, bar: 0}
 ```
 
-## `replace_if_let_with_match`
+
+[discrete]
+=== `replace_if_let_with_match`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_if_let_with_match.rs#L13[replace_if_let_with_match.rs]
 
 Replaces `if let` with an else branch with a `match` expression.
 
+.Before
 ```rust
-// BEFORE
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -708,8 +885,10 @@ fn handle(action: Action) {
         bar()
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -720,20 +899,25 @@ fn handle(action: Action) {
 }
 ```
 
-## `replace_let_with_if_let`
+
+[discrete]
+=== `replace_let_with_if_let`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_let_with_if_let.rs#L14[replace_let_with_if_let.rs]
 
 Replaces `let` with an `if-let`.
 
+.Before
 ```rust
-// BEFORE
 
 fn main(action: Action) {
     ┃let x = compute();
 }
 
 fn compute() -> Option<i32> { None }
+```
 
-// AFTER
+.After
+```rust
 
 fn main(action: Action) {
     if let Some(x) = compute() {
@@ -743,33 +927,43 @@ fn main(action: Action) {
 fn compute() -> Option<i32> { None }
 ```
 
-## `replace_qualified_name_with_use`
+
+[discrete]
+=== `replace_qualified_name_with_use`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_qualified_name_with_use.rs#L6[replace_qualified_name_with_use.rs]
 
 Adds a use statement for a given fully-qualified name.
 
+.Before
 ```rust
-// BEFORE
 fn process(map: std::collections::┃HashMap<String, String>) {}
+```
 
-// AFTER
+.After
+```rust
 use std::collections::HashMap;
 
 fn process(map: HashMap<String, String>) {}
 ```
 
-## `replace_unwrap_with_match`
+
+[discrete]
+=== `replace_unwrap_with_match`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_unwrap_with_match.rs#L17[replace_unwrap_with_match.rs]
 
 Replaces `unwrap` a `match` expression. Works for Result and Option.
 
+.Before
 ```rust
-// BEFORE
 enum Result<T, E> { Ok(T), Err(E) }
 fn main() {
     let x: Result<i32, i32> = Result::Ok(92);
     let y = x.┃unwrap();
 }
+```
 
-// AFTER
+.After
+```rust
 enum Result<T, E> { Ok(T), Err(E) }
 fn main() {
     let x: Result<i32, i32> = Result::Ok(92);
@@ -780,31 +974,41 @@ fn main() {
 }
 ```
 
-## `split_import`
+
+[discrete]
+=== `split_import`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/split_import.rs#L7[split_import.rs]
 
 Wraps the tail of import into braces.
 
+.Before
 ```rust
-// BEFORE
 use std::┃collections::HashMap;
+```
 
-// AFTER
+.After
+```rust
 use std::{collections::HashMap};
 ```
 
-## `unwrap_block`
+
+[discrete]
+=== `unwrap_block`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/unwrap_block.rs#L9[unwrap_block.rs]
 
 This assist removes if...else, for, while and loop control statements to just keep the body.
 
+.Before
 ```rust
-// BEFORE
 fn foo() {
     if true {┃
         println!("foo");
     }
 }
+```
 
-// AFTER
+.After
+```rust
 fn foo() {
     println!("foo");
 }
diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc
index 803073d55..12812fa0b 100644
--- a/docs/user/generated_features.adoc
+++ b/docs/user/generated_features.adoc
@@ -1,5 +1,5 @@
 === Expand Macro Recursively
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs[expand_macro.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs#L15[expand_macro.rs]
 
 Shows the full macro expansion of the macro at current cursor.
 
@@ -11,7 +11,7 @@ Shows the full macro expansion of the macro at current cursor.
 
 
 === Extend Selection
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs[extend_selection.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs#L15[extend_selection.rs]
 
 Extends the current selection to the encompassing syntactic construct
 (expression, statement, item, module, etc). It works with multiple cursors.
@@ -24,7 +24,7 @@ Extends the current selection to the encompassing syntactic construct
 
 
 === File Structure
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/display/structure.rs[structure.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/display/structure.rs#L17[structure.rs]
 
 Provides a tree of the symbols defined in the file. Can be used to
 
@@ -40,7 +40,7 @@ Provides a tree of the symbols defined in the file. Can be used to
 
 
 === Go to Definition
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs[goto_definition.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs#L18[goto_definition.rs]
 
 Navigates to the definition of an identifier.
 
@@ -52,7 +52,7 @@ Navigates to the definition of an identifier.
 
 
 === Go to Implementation
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs[goto_implementation.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs#L7[goto_implementation.rs]
 
 Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
 
@@ -64,7 +64,7 @@ Navigates to the impl block of structs, enums or traits. Also implemented as a c
 
 
 === Go to Type Definition
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs[goto_type_definition.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs#L6[goto_type_definition.rs]
 
 Navigates to the type of an identifier.
 
@@ -76,14 +76,14 @@ Navigates to the type of an identifier.
 
 
 === Hover
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs[hover.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs#L63[hover.rs]
 
 Shows additional information, like type of an expression or documentation for definition when "focusing" code.
 Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
 
 
 === Inlay Hints
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs[inlay_hints.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs#L40[inlay_hints.rs]
 
 rust-analyzer shows additional information inline with the source code.
 Editors usually render this using read-only virtual text snippets interspersed with code.
@@ -106,7 +106,7 @@ https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.co
 
 
 === Join Lines
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs[join_lines.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs#L12[join_lines.rs]
 
 Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.
 
@@ -118,7 +118,7 @@ Join selected lines into one, smartly fixing up whitespace, trailing commas, and
 
 
 === Magic Completions
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs[completion.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs#L38[completion.rs]
 
 In addition to usual reference completion, rust-analyzer provides some ✨magic✨
 completions as well:
@@ -163,7 +163,7 @@ mod tests {
 
 
 === Matching Brace
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs[matching_brace.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs#L3[matching_brace.rs]
 
 If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
 moves cursor to the matching brace. It uses the actual parser to determine
@@ -177,7 +177,7 @@ braces, so it won't confuse generics with comparisons.
 
 
 === On Typing Assists
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs[typing.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs#L35[typing.rs]
 
 Some features trigger on typing certain characters:
 
@@ -187,7 +187,7 @@ Some features trigger on typing certain characters:
 
 
 === Parent Module
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/parent_module.rs[parent_module.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/parent_module.rs#L12[parent_module.rs]
 
 Navigates to the parent module of the current module.
 
@@ -199,7 +199,7 @@ Navigates to the parent module of the current module.
 
 
 === Run
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs[runnables.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs#L45[runnables.rs]
 
 Shows a popup suggesting to run a test/benchmark/binary **at the current cursor
 location**. Super useful for repeatedly running just a single test. Do bind this
@@ -213,7 +213,7 @@ to a shortcut!
 
 
 === Semantic Syntax Highlighting
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs[syntax_highlighting.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs#L33[syntax_highlighting.rs]
 
 rust-analyzer highlights the code semantically.
 For example, `bar` in `foo::Bar` might be colored differently depending on whether `Bar` is an enum or a trait.
@@ -225,7 +225,7 @@ We also give special modifier for `mut` and `&mut` local variables.
 
 
 === Show Syntax Tree
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs[syntax_tree.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs#L9[syntax_tree.rs]
 
 Shows the parse tree of the current file. It exists mostly for debugging
 rust-analyzer itself.
@@ -238,7 +238,7 @@ rust-analyzer itself.
 
 
 === Status
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs[status.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs#L27[status.rs]
 
 Shows internal statistic about memory usage of rust-analyzer.
 
@@ -250,7 +250,7 @@ Shows internal statistic about memory usage of rust-analyzer.
 
 
 === Structural Seach and Replace
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs[ssr.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs#L26[ssr.rs]
 
 Search and replace with named wildcards that will match any expression.
 The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`.
@@ -275,7 +275,7 @@ String::from((y + 5).foo(z))
 
 
 === Workspace Symbol
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs[symbol_index.rs]
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs#L113[symbol_index.rs]
 
 Uses fuzzy-search to find types, modules and functions by name across your
 project and dependencies. This is **the** most useful feature, which improves code
diff --git a/docs/user/readme.adoc b/docs/user/manual.adoc
index 12def7327..202783fd9 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/manual.adoc
@@ -2,12 +2,7 @@
 :toc: preamble
 :sectanchors:
 :page-layout: post
-// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions
-:tip-caption: :bulb:
-:note-caption: :information_source:
-:important-caption: :heavy_exclamation_mark:
-:caution-caption: :fire:
-:warning-caption: :warning:
+:icons: font
 :source-highlighter: rouge
 :experimental:
 
@@ -19,7 +14,7 @@ https://microsoft.github.io/language-server-protocol/[Language Server Protocol]
 The LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic features like completion or goto definition by talking to an external language server process.
 
 To improve this document, send a pull request against
-https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/readme.adoc[this file].
+https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[this file].
 
 If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum.
 
@@ -67,16 +62,6 @@ The server binary is stored in:
 
 Note that we only support two most recent versions of VS Code.
 
-==== Special `when` clause context for keybindings.
-You may use `inRustProject` context to configure keybindings for rust projects only. For example:
-[source,json]
-----
-{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", "when": "inDebugMode && !inRustProject"},
-{ "key": "ctrl+shift+f5", "command": "rust-analyzer.debug", "when": "inRustProject"},
-{ "key": "ctrl+i", "command": "rust-analyzer.toggleInlayHints", "when": "inRustProject" }
-----
-More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
-
 ==== Updates
 
 The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed.
@@ -124,10 +109,23 @@ Here are some useful self-diagnostic commands:
 * To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel.
 * To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools.
 
+==== Special `when` clause context for keybindings.
+You may use `inRustProject` context to configure keybindings for rust projects only. For example:
+[source,json]
+----
+{
+  "key": "ctrl+i",
+  "command": "rust-analyzer.toggleInlayHints",
+  "when": "inRustProject"
+}
+----
+More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
+
 === rust-analyzer Language Server Binary
 
 Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
-You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page. Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`.
+You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page.
+Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`.
 
 On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used
 
@@ -147,7 +145,8 @@ $ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyz
 $ cargo xtask install --server
 ----
 
-If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue]. On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help.
+If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue].
+On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help.
 
 ==== Arch Linux
 
@@ -278,5 +277,6 @@ include::./generated_features.adoc[]
 
 Assists, or code actions, are small local refactorings, available in a particular context.
 They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
+Cursor position or selection is signified by `┃` character.
 
-See [assists.md](./assists.md) for the list of available assists.
+include::./generated_assists.adoc[]