53 files changed, 1620 insertions, 835 deletions

diff --git a/.gitignore b/.gitignore
index f835edef0..dab51647d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,4 +7,4 @@ crates/*/target
 *.log
 *.iml
 .vscode/settings.json
-cargo-timing*.html
+*.html
diff --git a/Cargo.lock b/Cargo.lock
index 07f18c760..af27bfc85 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -243,9 +243,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-queue"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c695eeca1e7173472a32221542ae469b3e9aac3a4fc81f7696bcad82029493db"
+checksum = "ab6bffe714b6bb07e42f201352c34f51fefd355ace793f9e638ebd52d23f98d2"
 dependencies = [
  "cfg-if",
  "crossbeam-utils",
@@ -640,9 +640,9 @@ dependencies = [
 
 [[package]]
 name = "lsp-types"
-version = "0.74.1"
+version = "0.74.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57c0e6a2b8837d27b29deb3f3e6dc1c6d2f57947677f9be1024e482ec5b59525"
+checksum = "b360754e89e0e13c114245131382ba921d4ff1efabb918e549422938aaa8d392"
 dependencies = [
  "base64",
  "bitflags",
@@ -809,9 +809,9 @@ dependencies = [
 
 [[package]]
 name = "paste"
-version = "0.1.14"
+version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3431e8f72b90f8a7af91dec890d9814000cb371258e0ec7370d93e085361f531"
+checksum = "d53181dcd37421c08d3b69f887784956674d09c3f9a47a04fece2b130a5b346b"
 dependencies = [
  "paste-impl",
  "proc-macro-hack",
@@ -819,9 +819,9 @@ dependencies = [
 
 [[package]]
 name = "paste-impl"
-version = "0.1.14"
+version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "25af5fc872ba284d8d84608bf8a0fa9b5376c96c23f503b007dfd9e34dde5606"
+checksum = "05ca490fa1c034a71412b4d1edcb904ec5a0981a4426c9eb2128c0fda7a68d17"
 dependencies = [
  "proc-macro-hack",
  "proc-macro2",
@@ -1292,9 +1292,9 @@ checksum = "2439c63f3f6139d1b57529d16bc3b8bb855230c8efcc5d3a896c8bea7c3b1e84"
 
 [[package]]
 name = "regex"
-version = "1.3.7"
+version = "1.3.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6020f034922e3194c711b82a627453881bc4682166cabb07134a10c26ba7692"
+checksum = "9c3780fcf44b193bc4d09f36d2a3c87b251da4a046c87795a0d35f4f927ad8e6"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -1304,9 +1304,9 @@ dependencies = [
 
 [[package]]
 name = "regex-syntax"
-version = "0.6.17"
+version = "0.6.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fe5bd57d1d7414c6b5ed48563a2c855d995ff777729dcd91c369ec7fea395ae"
+checksum = "26412eb97c6b088a6997e05f69403a802a92d520de2f8e63c2b65f9e0f47c4e8"
 
 [[package]]
 name = "relative-path"
@@ -1492,18 +1492,18 @@ checksum = "388a1df253eca08550bef6c72392cfe7c30914bf41df5269b68cbd6ff8f570a3"
 
 [[package]]
 name = "serde"
-version = "1.0.110"
+version = "1.0.111"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "99e7b308464d16b56eba9964e4972a3eee817760ab60d88c3f86e1fecb08204c"
+checksum = "c9124df5b40cbd380080b2cc6ab894c040a3070d995f5c9dc77e18c34a8ae37d"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.110"
+version = "1.0.111"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "818fbf6bfa9a42d3bfcaca148547aa00c7b915bec71d1757aa2d44ca68771984"
+checksum = "3f2c3ac8e6ca1e9c80b8be1023940162bf81ae3cffbb1809474152f2ce1eb250"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1577,9 +1577,9 @@ checksum = "ab16ced94dbd8a46c82fd81e3ed9a8727dac2977ea869d217bcc4ea1f122e81f"
 
 [[package]]
 name = "syn"
-version = "1.0.25"
+version = "1.0.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f14a640819f79b72a710c0be059dce779f9339ae046c8bef12c361d56702146f"
+checksum = "bb37da98a55b1d08529362d9cbb863be17556873df2585904ab9d2bc951291d0"
 dependencies = [
  "proc-macro2",
  "quote",
diff --git a/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs b/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs
index 6a675e812..776bddf91 100644
--- a/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs
+++ b/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs
@@ -4,9 +4,9 @@ use test_utils::mark;
 
 use crate::{utils::FamousDefs, AssistContext, AssistId, Assists};
 
-// Assist add_from_impl_for_enum
+// Assist: add_from_impl_for_enum
 //
-// Adds a From impl for an enum variant with one tuple field
+// Adds a From impl for an enum variant with one tuple field.
 //
 // ```
 // enum A { <|>One(u32) }
diff --git a/crates/ra_assists/src/handlers/change_lifetime_anon_to_named.rs b/crates/ra_assists/src/handlers/introduce_named_lifetime.rs
index 999aec421..beb5b7366 100644
--- a/crates/ra_assists/src/handlers/change_lifetime_anon_to_named.rs
+++ b/crates/ra_assists/src/handlers/introduce_named_lifetime.rs
@@ -1,12 +1,15 @@
-use crate::{assist_context::AssistBuilder, AssistContext, AssistId, Assists};
-use ast::{NameOwner, ParamList, TypeAscriptionOwner, TypeParamList, TypeRef};
-use ra_syntax::{ast, ast::TypeParamsOwner, AstNode, SyntaxKind, TextRange, TextSize};
+use ra_syntax::{
+    ast::{self, NameOwner, TypeAscriptionOwner, TypeParamsOwner},
+    AstNode, SyntaxKind, TextRange, TextSize,
+};
 use rustc_hash::FxHashSet;
 
-static ASSIST_NAME: &str = "change_lifetime_anon_to_named";
-static ASSIST_LABEL: &str = "Give anonymous lifetime a name";
+use crate::{assist_context::AssistBuilder, AssistContext, AssistId, Assists};
+
+static ASSIST_NAME: &str = "introduce_named_lifetime";
+static ASSIST_LABEL: &str = "Introduce named lifetime";
 
-// Assist: change_lifetime_anon_to_named
+// Assist: introduce_named_lifetime
 //
 // Change an anonymous lifetime to a named lifetime.
 //
@@ -31,7 +34,7 @@ static ASSIST_LABEL: &str = "Give anonymous lifetime a name";
 // ```
 // FIXME: How can we handle renaming any one of multiple anonymous lifetimes?
 // FIXME: should also add support for the case fun(f: &Foo) -> &<|>Foo
-pub(crate) fn change_lifetime_anon_to_named(acc: &mut Assists, ctx: &AssistContext) -> Option<()> {
+pub(crate) fn introduce_named_lifetime(acc: &mut Assists, ctx: &AssistContext) -> Option<()> {
     let lifetime_token = ctx
         .find_token_at_offset(SyntaxKind::LIFETIME)
         .filter(|lifetime| lifetime.text() == "'_")?;
@@ -52,7 +55,7 @@ fn generate_fn_def_assist(
     fn_def: &ast::FnDef,
     lifetime_loc: TextRange,
 ) -> Option<()> {
-    let param_list: ParamList = fn_def.param_list()?;
+    let param_list: ast::ParamList = fn_def.param_list()?;
     let new_lifetime_param = generate_unique_lifetime_param_name(&fn_def.type_param_list())?;
     let end_of_fn_ident = fn_def.name()?.ident_token()?.text_range().end();
     let self_param =
@@ -67,7 +70,7 @@ fn generate_fn_def_assist(
         let fn_params_without_lifetime: Vec<_> = param_list
             .params()
             .filter_map(|param| match param.ascribed_type() {
-                Some(TypeRef::ReferenceType(ascribed_type))
+                Some(ast::TypeRef::ReferenceType(ascribed_type))
                     if ascribed_type.lifetime_token() == None =>
                 {
                     Some(ascribed_type.amp_token()?.text_range().end())
@@ -106,7 +109,7 @@ fn generate_impl_def_assist(
 /// Given a type parameter list, generate a unique lifetime parameter name
 /// which is not in the list
 fn generate_unique_lifetime_param_name(
-    existing_type_param_list: &Option<TypeParamList>,
+    existing_type_param_list: &Option<ast::TypeParamList>,
 ) -> Option<char> {
     match existing_type_param_list {
         Some(type_params) => {
@@ -151,7 +154,7 @@ mod tests {
     #[test]
     fn test_example_case() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"impl Cursor<'_<|>> {
                 fn node(self) -> &SyntaxNode {
                     match self {
@@ -172,7 +175,7 @@ mod tests {
     #[test]
     fn test_example_case_simplified() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"impl Cursor<'_<|>> {"#,
             r#"impl<'a> Cursor<'a> {"#,
         );
@@ -181,7 +184,7 @@ mod tests {
     #[test]
     fn test_example_case_cursor_after_tick() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"impl Cursor<'<|>_> {"#,
             r#"impl<'a> Cursor<'a> {"#,
         );
@@ -190,7 +193,7 @@ mod tests {
     #[test]
     fn test_example_case_cursor_before_tick() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"impl Cursor<<|>'_> {"#,
             r#"impl<'a> Cursor<'a> {"#,
         );
@@ -198,23 +201,20 @@ mod tests {
 
     #[test]
     fn test_not_applicable_cursor_position() {
-        check_assist_not_applicable(change_lifetime_anon_to_named, r#"impl Cursor<'_><|> {"#);
-        check_assist_not_applicable(change_lifetime_anon_to_named, r#"impl Cursor<|><'_> {"#);
+        check_assist_not_applicable(introduce_named_lifetime, r#"impl Cursor<'_><|> {"#);
+        check_assist_not_applicable(introduce_named_lifetime, r#"impl Cursor<|><'_> {"#);
     }
 
     #[test]
     fn test_not_applicable_lifetime_already_name() {
-        check_assist_not_applicable(change_lifetime_anon_to_named, r#"impl Cursor<'a<|>> {"#);
-        check_assist_not_applicable(
-            change_lifetime_anon_to_named,
-            r#"fn my_fun<'a>() -> X<'a<|>>"#,
-        );
+        check_assist_not_applicable(introduce_named_lifetime, r#"impl Cursor<'a<|>> {"#);
+        check_assist_not_applicable(introduce_named_lifetime, r#"fn my_fun<'a>() -> X<'a<|>>"#);
     }
 
     #[test]
     fn test_with_type_parameter() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"impl<T> Cursor<T, '_<|>>"#,
             r#"impl<T, 'a> Cursor<T, 'a>"#,
         );
@@ -223,7 +223,7 @@ mod tests {
     #[test]
     fn test_with_existing_lifetime_name_conflict() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"impl<'a, 'b> Cursor<'a, 'b, '_<|>>"#,
             r#"impl<'a, 'b, 'c> Cursor<'a, 'b, 'c>"#,
         );
@@ -232,7 +232,7 @@ mod tests {
     #[test]
     fn test_function_return_value_anon_lifetime_param() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun() -> X<'_<|>>"#,
             r#"fn my_fun<'a>() -> X<'a>"#,
         );
@@ -241,7 +241,7 @@ mod tests {
     #[test]
     fn test_function_return_value_anon_reference_lifetime() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun() -> &'_<|> X"#,
             r#"fn my_fun<'a>() -> &'a X"#,
         );
@@ -250,7 +250,7 @@ mod tests {
     #[test]
     fn test_function_param_anon_lifetime() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun(x: X<'_<|>>)"#,
             r#"fn my_fun<'a>(x: X<'a>)"#,
         );
@@ -259,7 +259,7 @@ mod tests {
     #[test]
     fn test_function_add_lifetime_to_params() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun(f: &Foo) -> X<'_<|>>"#,
             r#"fn my_fun<'a>(f: &'a Foo) -> X<'a>"#,
         );
@@ -268,7 +268,7 @@ mod tests {
     #[test]
     fn test_function_add_lifetime_to_params_in_presence_of_other_lifetime() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun<'other>(f: &Foo, b: &'other Bar) -> X<'_<|>>"#,
             r#"fn my_fun<'other, 'a>(f: &'a Foo, b: &'other Bar) -> X<'a>"#,
         );
@@ -278,7 +278,7 @@ mod tests {
     fn test_function_not_applicable_without_self_and_multiple_unnamed_param_lifetimes() {
         // this is not permitted under lifetime elision rules
         check_assist_not_applicable(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun(f: &Foo, b: &Bar) -> X<'_<|>>"#,
         );
     }
@@ -286,7 +286,7 @@ mod tests {
     #[test]
     fn test_function_add_lifetime_to_self_ref_param() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun<'other>(&self, f: &Foo, b: &'other Bar) -> X<'_<|>>"#,
             r#"fn my_fun<'other, 'a>(&'a self, f: &Foo, b: &'other Bar) -> X<'a>"#,
         );
@@ -295,7 +295,7 @@ mod tests {
     #[test]
     fn test_function_add_lifetime_to_param_with_non_ref_self() {
         check_assist(
-            change_lifetime_anon_to_named,
+            introduce_named_lifetime,
             r#"fn my_fun<'other>(self, f: &Foo, b: &'other Bar) -> X<'_<|>>"#,
             r#"fn my_fun<'other, 'a>(self, f: &'a Foo, b: &'other Bar) -> X<'a>"#,
         );
diff --git a/crates/ra_assists/src/lib.rs b/crates/ra_assists/src/lib.rs
index 3f8f7ffbf..fb5d59a87 100644
--- a/crates/ra_assists/src/lib.rs
+++ b/crates/ra_assists/src/lib.rs
@@ -112,7 +112,6 @@ mod handlers {
     mod add_turbo_fish;
     mod apply_demorgan;
     mod auto_import;
-    mod change_lifetime_anon_to_named;
     mod change_return_type_to_result;
     mod change_visibility;
     mod early_return;
@@ -122,6 +121,7 @@ mod handlers {
     mod flip_comma;
     mod flip_trait_bound;
     mod inline_local_variable;
+    mod introduce_named_lifetime;
     mod introduce_variable;
     mod invert_if;
     mod merge_imports;
@@ -152,7 +152,6 @@ mod handlers {
             add_turbo_fish::add_turbo_fish,
             apply_demorgan::apply_demorgan,
             auto_import::auto_import,
-            change_lifetime_anon_to_named::change_lifetime_anon_to_named,
             change_return_type_to_result::change_return_type_to_result,
             change_visibility::change_visibility,
             early_return::convert_to_guarded_return,
@@ -162,6 +161,7 @@ mod handlers {
             flip_comma::flip_comma,
             flip_trait_bound::flip_trait_bound,
             inline_local_variable::inline_local_variable,
+            introduce_named_lifetime::introduce_named_lifetime,
             introduce_variable::introduce_variable,
             invert_if::invert_if,
             merge_imports::merge_imports,
diff --git a/crates/ra_assists/src/tests/generated.rs b/crates/ra_assists/src/tests/generated.rs
index abffbf97c..d17504529 100644
--- a/crates/ra_assists/src/tests/generated.rs
+++ b/crates/ra_assists/src/tests/generated.rs
@@ -59,6 +59,25 @@ fn main() {
 }
 
 #[test]
+fn doctest_add_from_impl_for_enum() {
+    check_doc_test(
+        "add_from_impl_for_enum",
+        r#####"
+enum A { <|>One(u32) }
+"#####,
+        r#####"
+enum A { One(u32) }
+
+impl From<u32> for A {
+    fn from(v: u32) -> Self {
+        A::One(v)
+    }
+}
+"#####,
+    )
+}
+
+#[test]
 fn doctest_add_function() {
     check_doc_test(
         "add_function",
@@ -269,31 +288,6 @@ pub mod std { pub mod collections { pub struct HashMap { } } }
 }
 
 #[test]
-fn doctest_change_lifetime_anon_to_named() {
-    check_doc_test(
-        "change_lifetime_anon_to_named",
-        r#####"
-impl Cursor<'_<|>> {
-    fn node(self) -> &SyntaxNode {
-        match self {
-            Cursor::Replace(node) | Cursor::Before(node) => node,
-        }
-    }
-}
-"#####,
-        r#####"
-impl<'a> Cursor<'a> {
-    fn node(self) -> &SyntaxNode {
-        match self {
-            Cursor::Replace(node) | Cursor::Before(node) => node,
-        }
-    }
-}
-"#####,
-    )
-}
-
-#[test]
 fn doctest_change_return_type_to_result() {
     check_doc_test(
         "change_return_type_to_result",
@@ -458,6 +452,31 @@ fn main() {
 }
 
 #[test]
+fn doctest_introduce_named_lifetime() {
+    check_doc_test(
+        "introduce_named_lifetime",
+        r#####"
+impl Cursor<'_<|>> {
+    fn node(self) -> &SyntaxNode {
+        match self {
+            Cursor::Replace(node) | Cursor::Before(node) => node,
+        }
+    }
+}
+"#####,
+        r#####"
+impl<'a> Cursor<'a> {
+    fn node(self) -> &SyntaxNode {
+        match self {
+            Cursor::Replace(node) | Cursor::Before(node) => node,
+        }
+    }
+}
+"#####,
+    )
+}
+
+#[test]
 fn doctest_introduce_variable() {
     check_doc_test(
         "introduce_variable",
diff --git a/crates/ra_hir_def/src/body/lower.rs b/crates/ra_hir_def/src/body/lower.rs
index 905c0cf5d..f159f80af 100644
--- a/crates/ra_hir_def/src/body/lower.rs
+++ b/crates/ra_hir_def/src/body/lower.rs
@@ -134,7 +134,7 @@ impl ExprCollector<'_> {
         self.make_expr(expr, Err(SyntheticSyntax))
     }
     fn empty_block(&mut self) -> ExprId {
-        self.alloc_expr_desugared(Expr::Block { statements: Vec::new(), tail: None })
+        self.alloc_expr_desugared(Expr::Block { statements: Vec::new(), tail: None, label: None })
     }
     fn missing_expr(&mut self) -> ExprId {
         self.alloc_expr_desugared(Expr::Missing)
@@ -215,7 +215,16 @@ impl ExprCollector<'_> {
             ast::Expr::BlockExpr(e) => self.collect_block(e),
             ast::Expr::LoopExpr(e) => {
                 let body = self.collect_block_opt(e.loop_body());
-                self.alloc_expr(Expr::Loop { body }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::Loop {
+                        body,
+                        label: e
+                            .label()
+                            .and_then(|l| l.lifetime_token())
+                            .map(|l| Name::new_lifetime(&l)),
+                    },
+                    syntax_ptr,
+                )
             }
             ast::Expr::WhileExpr(e) => {
                 let body = self.collect_block_opt(e.loop_body());
@@ -230,25 +239,56 @@ impl ExprCollector<'_> {
                             let pat = self.collect_pat(pat);
                             let match_expr = self.collect_expr_opt(condition.expr());
                             let placeholder_pat = self.missing_pat();
-                            let break_ = self.alloc_expr_desugared(Expr::Break { expr: None });
+                            let break_ =
+                                self.alloc_expr_desugared(Expr::Break { expr: None, label: None });
                             let arms = vec![
                                 MatchArm { pat, expr: body, guard: None },
                                 MatchArm { pat: placeholder_pat, expr: break_, guard: None },
                             ];
                             let match_expr =
                                 self.alloc_expr_desugared(Expr::Match { expr: match_expr, arms });
-                            return self.alloc_expr(Expr::Loop { body: match_expr }, syntax_ptr);
+                            return self.alloc_expr(
+                                Expr::Loop {
+                                    body: match_expr,
+                                    label: e
+                                        .label()
+                                        .and_then(|l| l.lifetime_token())
+                                        .map(|l| Name::new_lifetime(&l)),
+                                },
+                                syntax_ptr,
+                            );
                         }
                     },
                 };
 
-                self.alloc_expr(Expr::While { condition, body }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::While {
+                        condition,
+                        body,
+                        label: e
+                            .label()
+                            .and_then(|l| l.lifetime_token())
+                            .map(|l| Name::new_lifetime(&l)),
+                    },
+                    syntax_ptr,
+                )
             }
             ast::Expr::ForExpr(e) => {
                 let iterable = self.collect_expr_opt(e.iterable());
                 let pat = self.collect_pat_opt(e.pat());
                 let body = self.collect_block_opt(e.loop_body());
-                self.alloc_expr(Expr::For { iterable, pat, body }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::For {
+                        iterable,
+                        pat,
+                        body,
+                        label: e
+                            .label()
+                            .and_then(|l| l.lifetime_token())
+                            .map(|l| Name::new_lifetime(&l)),
+                    },
+                    syntax_ptr,
+                )
             }
             ast::Expr::CallExpr(e) => {
                 let callee = self.collect_expr_opt(e.expr());
@@ -301,13 +341,16 @@ impl ExprCollector<'_> {
                     .unwrap_or(Expr::Missing);
                 self.alloc_expr(path, syntax_ptr)
             }
-            ast::Expr::ContinueExpr(_e) => {
-                // FIXME: labels
-                self.alloc_expr(Expr::Continue, syntax_ptr)
-            }
+            ast::Expr::ContinueExpr(e) => self.alloc_expr(
+                Expr::Continue { label: e.lifetime_token().map(|l| Name::new_lifetime(&l)) },
+                syntax_ptr,
+            ),
             ast::Expr::BreakExpr(e) => {
                 let expr = e.expr().map(|e| self.collect_expr(e));
-                self.alloc_expr(Expr::Break { expr }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::Break { expr, label: e.lifetime_token().map(|l| Name::new_lifetime(&l)) },
+                    syntax_ptr,
+                )
             }
             ast::Expr::ParenExpr(e) => {
                 let inner = self.collect_expr_opt(e.expr());
@@ -529,7 +572,8 @@ impl ExprCollector<'_> {
             })
             .collect();
         let tail = block.expr().map(|e| self.collect_expr(e));
-        self.alloc_expr(Expr::Block { statements, tail }, syntax_node_ptr)
+        let label = block.label().and_then(|l| l.lifetime_token()).map(|t| Name::new_lifetime(&t));
+        self.alloc_expr(Expr::Block { statements, tail, label }, syntax_node_ptr)
     }
 
     fn collect_block_items(&mut self, block: &ast::BlockExpr) {
diff --git a/crates/ra_hir_def/src/body/scope.rs b/crates/ra_hir_def/src/body/scope.rs
index 09e92b74e..e48ff38f9 100644
--- a/crates/ra_hir_def/src/body/scope.rs
+++ b/crates/ra_hir_def/src/body/scope.rs
@@ -138,10 +138,10 @@ fn compute_block_scopes(
 fn compute_expr_scopes(expr: ExprId, body: &Body, scopes: &mut ExprScopes, scope: ScopeId) {
     scopes.set_scope(expr, scope);
     match &body[expr] {
-        Expr::Block { statements, tail } => {
+        Expr::Block { statements, tail, .. } => {
             compute_block_scopes(&statements, *tail, body, scopes, scope);
         }
-        Expr::For { iterable, pat, body: body_expr } => {
+        Expr::For { iterable, pat, body: body_expr, .. } => {
             compute_expr_scopes(*iterable, body, scopes, scope);
             let scope = scopes.new_scope(scope);
             scopes.add_bindings(body, scope, *pat);
diff --git a/crates/ra_hir_def/src/expr.rs b/crates/ra_hir_def/src/expr.rs
index f25c6f958..ca49b26d1 100644
--- a/crates/ra_hir_def/src/expr.rs
+++ b/crates/ra_hir_def/src/expr.rs
@@ -52,18 +52,22 @@ pub enum Expr {
     Block {
         statements: Vec<Statement>,
         tail: Option<ExprId>,
+        label: Option<Name>,
     },
     Loop {
         body: ExprId,
+        label: Option<Name>,
     },
     While {
         condition: ExprId,
         body: ExprId,
+        label: Option<Name>,
     },
     For {
         iterable: ExprId,
         pat: PatId,
         body: ExprId,
+        label: Option<Name>,
     },
     Call {
         callee: ExprId,
@@ -79,9 +83,12 @@ pub enum Expr {
         expr: ExprId,
         arms: Vec<MatchArm>,
     },
-    Continue,
+    Continue {
+        label: Option<Name>,
+    },
     Break {
         expr: Option<ExprId>,
+        label: Option<Name>,
     },
     Return {
         expr: Option<ExprId>,
@@ -225,7 +232,7 @@ impl Expr {
                     f(*else_branch);
                 }
             }
-            Expr::Block { statements, tail } => {
+            Expr::Block { statements, tail, .. } => {
                 for stmt in statements {
                     match stmt {
                         Statement::Let { initializer, .. } => {
@@ -241,8 +248,8 @@ impl Expr {
                 }
             }
             Expr::TryBlock { body } => f(*body),
-            Expr::Loop { body } => f(*body),
-            Expr::While { condition, body } => {
+            Expr::Loop { body, .. } => f(*body),
+            Expr::While { condition, body, .. } => {
                 f(*condition);
                 f(*body);
             }
@@ -268,8 +275,8 @@ impl Expr {
                     f(arm.expr);
                 }
             }
-            Expr::Continue => {}
-            Expr::Break { expr } | Expr::Return { expr } => {
+            Expr::Continue { .. } => {}
+            Expr::Break { expr, .. } | Expr::Return { expr } => {
                 if let Some(expr) = expr {
                     f(*expr);
                 }
diff --git a/crates/ra_hir_expand/src/name.rs b/crates/ra_hir_expand/src/name.rs
index fecce224e..ea495cb11 100644
--- a/crates/ra_hir_expand/src/name.rs
+++ b/crates/ra_hir_expand/src/name.rs
@@ -37,6 +37,11 @@ impl Name {
         Name(Repr::TupleField(idx))
     }
 
+    pub fn new_lifetime(lt: &ra_syntax::SyntaxToken) -> Name {
+        assert!(lt.kind() == ra_syntax::SyntaxKind::LIFETIME);
+        Name(Repr::Text(lt.text().clone()))
+    }
+
     /// Shortcut to create inline plain text name
     const fn new_inline_ascii(text: &[u8]) -> Name {
         Name::new_text(SmolStr::new_inline_from_ascii(text.len(), text))
diff --git a/crates/ra_hir_ty/src/infer.rs b/crates/ra_hir_ty/src/infer.rs
index 957d6e0b5..dc77e88e5 100644
--- a/crates/ra_hir_ty/src/infer.rs
+++ b/crates/ra_hir_ty/src/infer.rs
@@ -219,6 +219,17 @@ struct InferenceContext<'a> {
 struct BreakableContext {
     pub may_break: bool,
     pub break_ty: Ty,
+    pub label: Option<name::Name>,
+}
+
+fn find_breakable<'c>(
+    ctxs: &'c mut [BreakableContext],
+    label: Option<&name::Name>,
+) -> Option<&'c mut BreakableContext> {
+    match label {
+        Some(_) => ctxs.iter_mut().rev().find(|ctx| ctx.label.as_ref() == label),
+        None => ctxs.last_mut(),
+    }
 }
 
 impl<'a> InferenceContext<'a> {
diff --git a/crates/ra_hir_ty/src/infer/expr.rs b/crates/ra_hir_ty/src/infer/expr.rs
index 78084cb57..4a98e2deb 100644
--- a/crates/ra_hir_ty/src/infer/expr.rs
+++ b/crates/ra_hir_ty/src/infer/expr.rs
@@ -22,8 +22,8 @@ use crate::{
 };
 
 use super::{
-    BindingMode, BreakableContext, Diverges, Expectation, InferenceContext, InferenceDiagnostic,
-    TypeMismatch,
+    find_breakable, BindingMode, BreakableContext, Diverges, Expectation, InferenceContext,
+    InferenceDiagnostic, TypeMismatch,
 };
 
 impl<'a> InferenceContext<'a> {
@@ -86,16 +86,20 @@ impl<'a> InferenceContext<'a> {
 
                 self.coerce_merge_branch(&then_ty, &else_ty)
             }
-            Expr::Block { statements, tail } => self.infer_block(statements, *tail, expected),
+            Expr::Block { statements, tail, .. } => {
+                // FIXME: Breakable block inference
+                self.infer_block(statements, *tail, expected)
+            }
             Expr::TryBlock { body } => {
                 let _inner = self.infer_expr(*body, expected);
                 // FIXME should be std::result::Result<{inner}, _>
                 Ty::Unknown
             }
-            Expr::Loop { body } => {
+            Expr::Loop { body, label } => {
                 self.breakables.push(BreakableContext {
                     may_break: false,
                     break_ty: self.table.new_type_var(),
+                    label: label.clone(),
                 });
                 self.infer_expr(*body, &Expectation::has_type(Ty::unit()));
 
@@ -110,8 +114,12 @@ impl<'a> InferenceContext<'a> {
                     Ty::simple(TypeCtor::Never)
                 }
             }
-            Expr::While { condition, body } => {
-                self.breakables.push(BreakableContext { may_break: false, break_ty: Ty::Unknown });
+            Expr::While { condition, body, label } => {
+                self.breakables.push(BreakableContext {
+                    may_break: false,
+                    break_ty: Ty::Unknown,
+                    label: label.clone(),
+                });
                 // while let is desugared to a match loop, so this is always simple while
                 self.infer_expr(*condition, &Expectation::has_type(Ty::simple(TypeCtor::Bool)));
                 self.infer_expr(*body, &Expectation::has_type(Ty::unit()));
@@ -120,10 +128,14 @@ impl<'a> InferenceContext<'a> {
                 self.diverges = Diverges::Maybe;
                 Ty::unit()
             }
-            Expr::For { iterable, body, pat } => {
+            Expr::For { iterable, body, pat, label } => {
                 let iterable_ty = self.infer_expr(*iterable, &Expectation::none());
 
-                self.breakables.push(BreakableContext { may_break: false, break_ty: Ty::Unknown });
+                self.breakables.push(BreakableContext {
+                    may_break: false,
+                    break_ty: Ty::Unknown,
+                    label: label.clone(),
+                });
                 let pat_ty =
                     self.resolve_associated_type(iterable_ty, self.resolve_into_iter_item());
 
@@ -236,23 +248,24 @@ impl<'a> InferenceContext<'a> {
                 let resolver = resolver_for_expr(self.db.upcast(), self.owner, tgt_expr);
                 self.infer_path(&resolver, p, tgt_expr.into()).unwrap_or(Ty::Unknown)
             }
-            Expr::Continue => Ty::simple(TypeCtor::Never),
-            Expr::Break { expr } => {
+            Expr::Continue { .. } => Ty::simple(TypeCtor::Never),
+            Expr::Break { expr, label } => {
                 let val_ty = if let Some(expr) = expr {
                     self.infer_expr(*expr, &Expectation::none())
                 } else {
                     Ty::unit()
                 };
 
-                let last_ty = if let Some(ctxt) = self.breakables.last() {
-                    ctxt.break_ty.clone()
-                } else {
-                    Ty::Unknown
-                };
+                let last_ty =
+                    if let Some(ctxt) = find_breakable(&mut self.breakables, label.as_ref()) {
+                        ctxt.break_ty.clone()
+                    } else {
+                        Ty::Unknown
+                    };
 
                 let merged_type = self.coerce_merge_branch(&last_ty, &val_ty);
 
-                if let Some(ctxt) = self.breakables.last_mut() {
+                if let Some(ctxt) = find_breakable(&mut self.breakables, label.as_ref()) {
                     ctxt.break_ty = merged_type;
                     ctxt.may_break = true;
                 } else {
diff --git a/crates/ra_hir_ty/src/tests/simple.rs b/crates/ra_hir_ty/src/tests/simple.rs
index 839491b9e..88309157b 100644
--- a/crates/ra_hir_ty/src/tests/simple.rs
+++ b/crates/ra_hir_ty/src/tests/simple.rs
@@ -1943,3 +1943,57 @@ fn test() {
     "###
     );
 }
+
+#[test]
+fn infer_labelled_break_with_val() {
+    assert_snapshot!(
+        infer(r#"
+fn foo() {
+    let _x = || 'outer: loop {
+        let inner = 'inner: loop {
+            let i = Default::default();
+            if (break 'outer i) {
+                loop { break 'inner 5i8; };
+            } else if true {
+                break 'inner 6;
+            }
+            break 7;
+        };
+        break inner < 8;
+    };
+}
+"#),
+        @r###"
+    10..336 '{     ...  }; }': ()
+    20..22 '_x': || -> bool
+    25..333 '|| 'ou...     }': || -> bool
+    28..333 ''outer...     }': bool
+    41..333 '{     ...     }': ()
+    55..60 'inner': i8
+    63..301 ''inner...     }': i8
+    76..301 '{     ...     }': ()
+    94..95 'i': bool
+    98..114 'Defaul...efault': {unknown}
+    98..116 'Defaul...ault()': bool
+    130..270 'if (br...     }': ()
+    134..148 'break 'outer i': !
+    147..148 'i': bool
+    150..209 '{     ...     }': ()
+    168..194 'loop {...5i8; }': !
+    173..194 '{ brea...5i8; }': ()
+    175..191 'break ...er 5i8': !
+    188..191 '5i8': i8
+    215..270 'if tru...     }': ()
+    218..222 'true': bool
+    223..270 '{     ...     }': ()
+    241..255 'break 'inner 6': !
+    254..255 '6': i8
+    283..290 'break 7': !
+    289..290 '7': i8
+    311..326 'break inner < 8': !
+    317..322 'inner': i8
+    317..326 'inner < 8': bool
+    325..326 '8': i8
+    "###
+    );
+}
diff --git a/crates/ra_ide/src/completion.rs b/crates/ra_ide/src/completion.rs
index 191300704..d890b69d2 100644
--- a/crates/ra_ide/src/completion.rs
+++ b/crates/ra_ide/src/completion.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 mod completion_config;
 mod completion_item;
 mod completion_context;
@@ -35,6 +33,51 @@ pub use crate::completion::{
     completion_item::{CompletionItem, CompletionItemKind, CompletionScore, InsertTextFormat},
 };
 
+//FIXME: split the following feature into fine-grained features.
+
+// Feature: Magic Completions
+//
+// In addition to usual reference completion, rust-analyzer provides some ✨magic✨
+// completions as well:
+//
+// Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
+// is placed at the appropriate position. Even though `if` is easy to type, you
+// still want to complete it, to get ` { }` for free! `return` is inserted with a
+// space or `;` depending on the return type of the function.
+//
+// When completing a function call, `()` are automatically inserted. If a function
+// takes arguments, the cursor is positioned inside the parenthesis.
+//
+// There are postfix completions, which can be triggered by typing something like
+// `foo().if`. The word after `.` determines postfix completion. Possible variants are:
+//
+// - `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
+// - `expr.match` -> `match expr {}`
+// - `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
+// - `expr.ref` -> `&expr`
+// - `expr.refm` -> `&mut expr`
+// - `expr.not` -> `!expr`
+// - `expr.dbg` -> `dbg!(expr)`
+//
+// There also snippet completions:
+//
+// .Expressions
+// - `pd` -> `println!("{:?}")`
+// - `ppd` -> `println!("{:#?}")`
+//
+// .Items
+// - `tfn` -> `#[test] fn f(){}`
+// - `tmod` ->
+// ```rust
+// #[cfg(test)]
+// mod tests {
+//     use super::*;
+//
+//     #[test]
+//     fn test_fn() {}
+// }
+// ```
+
 /// Main entry point for completion. We run completion as a two-phase process.
 ///
 /// First, we look at the position and collect a so-called `CompletionContext.
diff --git a/crates/ra_ide/src/completion/complete_postfix.rs b/crates/ra_ide/src/completion/complete_postfix.rs
index 02e660ca8..59b58bf98 100644
--- a/crates/ra_ide/src/completion/complete_postfix.rs
+++ b/crates/ra_ide/src/completion/complete_postfix.rs
@@ -1,12 +1,11 @@
 //! FIXME: write short doc here
-
+use ra_assists::utils::TryEnum;
 use ra_syntax::{
     ast::{self, AstNode},
     TextRange, TextSize,
 };
 use ra_text_edit::TextEdit;
 
-use super::completion_config::SnippetCap;
 use crate::{
     completion::{
         completion_context::CompletionContext,
@@ -14,7 +13,8 @@ use crate::{
     },
     CompletionItem,
 };
-use ra_assists::utils::TryEnum;
+
+use super::completion_config::SnippetCap;
 
 pub(super) fn complete_postfix(acc: &mut Completions, ctx: &CompletionContext) {
     if !ctx.config.enable_postfix_completions {
diff --git a/crates/ra_ide/src/display/structure.rs b/crates/ra_ide/src/display/structure.rs
index 967eee5d2..aad5a8e4d 100644
--- a/crates/ra_ide/src/display/structure.rs
+++ b/crates/ra_ide/src/display/structure.rs
@@ -1,10 +1,6 @@
-//! FIXME: write short doc here
-
-use crate::TextRange;
-
 use ra_syntax::{
     ast::{self, AttrsOwner, NameOwner, TypeAscriptionOwner, TypeParamsOwner},
-    match_ast, AstNode, SourceFile, SyntaxKind, SyntaxNode, WalkEvent,
+    match_ast, AstNode, SourceFile, SyntaxKind, SyntaxNode, TextRange, WalkEvent,
 };
 
 #[derive(Debug, Clone)]
@@ -18,6 +14,19 @@ pub struct StructureNode {
     pub deprecated: bool,
 }
 
+// Feature: File Structure
+//
+// Provides a tree of the symbols defined in the file. Can be used to
+//
+// * fuzzy search symbol in a file (super useful)
+// * draw breadcrumbs to describe the context around the cursor
+// * draw outline of the file
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+Shift+O]
+// |===
 pub fn file_structure(file: &SourceFile) -> Vec<StructureNode> {
     let mut res = Vec::new();
     let mut stack = Vec::new();
diff --git a/crates/ra_ide/src/expand_macro.rs b/crates/ra_ide/src/expand_macro.rs
index f536ba3e7..54a47aac0 100644
--- a/crates/ra_ide/src/expand_macro.rs
+++ b/crates/ra_ide/src/expand_macro.rs
@@ -1,5 +1,3 @@
-//! This modules implements "expand macro" functionality in the IDE
-
 use hir::Semantics;
 use ra_ide_db::RootDatabase;
 use ra_syntax::{
@@ -14,6 +12,15 @@ pub struct ExpandedMacro {
     pub expansion: String,
 }
 
+// Feature: Expand Macro Recursively
+//
+// Shows the full macro expansion of the macro at current cursor.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Expand macro recursively**
+// |===
 pub(crate) fn expand_macro(db: &RootDatabase, position: FilePosition) -> Option<ExpandedMacro> {
     let sema = Semantics::new(db);
     let file = sema.parse(position.file_id);
diff --git a/crates/ra_ide/src/extend_selection.rs b/crates/ra_ide/src/extend_selection.rs
index 554594a43..a4bc93cdb 100644
--- a/crates/ra_ide/src/extend_selection.rs
+++ b/crates/ra_ide/src/extend_selection.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use std::iter::successors;
 
 use hir::Semantics;
@@ -14,6 +12,16 @@ use ra_syntax::{
 
 use crate::FileRange;
 
+// Feature: Extend Selection
+//
+// Extends the current selection to the encompassing syntactic construct
+// (expression, statement, item, module, etc). It works with multiple cursors.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+Shift+→]
+// |===
 pub(crate) fn extend_selection(db: &RootDatabase, frange: FileRange) -> TextRange {
     let sema = Semantics::new(db);
     let src = sema.parse(frange.file_id);
diff --git a/crates/ra_ide/src/goto_definition.rs b/crates/ra_ide/src/goto_definition.rs
index 90e85d419..a6c86e99c 100644
--- a/crates/ra_ide/src/goto_definition.rs
+++ b/crates/ra_ide/src/goto_definition.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::Semantics;
 use ra_ide_db::{
     defs::{classify_name, classify_name_ref},
@@ -17,6 +15,15 @@ use crate::{
     FilePosition, NavigationTarget, RangeInfo,
 };
 
+// Feature: Go to Definition
+//
+// Navigates to the definition of an identifier.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[F12]
+// |===
 pub(crate) fn goto_definition(
     db: &RootDatabase,
     position: FilePosition,
diff --git a/crates/ra_ide/src/impls.rs b/crates/ra_ide/src/goto_implementation.rs
index ea2225f70..0cec0657e 100644
--- a/crates/ra_ide/src/impls.rs
+++ b/crates/ra_ide/src/goto_implementation.rs
@@ -1,11 +1,18 @@
-//! FIXME: write short doc here
-
 use hir::{Crate, ImplDef, Semantics};
 use ra_ide_db::RootDatabase;
 use ra_syntax::{algo::find_node_at_offset, ast, AstNode};
 
 use crate::{display::ToNav, FilePosition, NavigationTarget, RangeInfo};
 
+// Feature: Go to Implementation
+//
+// Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+F12]
+// |===
 pub(crate) fn goto_implementation(
     db: &RootDatabase,
     position: FilePosition,
diff --git a/crates/ra_ide/src/goto_type_definition.rs b/crates/ra_ide/src/goto_type_definition.rs
index a84637489..91a3097fb 100644
--- a/crates/ra_ide/src/goto_type_definition.rs
+++ b/crates/ra_ide/src/goto_type_definition.rs
@@ -1,10 +1,17 @@
-//! FIXME: write short doc here
-
 use ra_ide_db::RootDatabase;
 use ra_syntax::{ast, match_ast, AstNode, SyntaxKind::*, SyntaxToken, TokenAtOffset};
 
 use crate::{display::ToNav, FilePosition, NavigationTarget, RangeInfo};
 
+// Feature: Go to Type Definition
+//
+// Navigates to the type of an identifier.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Go to Type Definition*
+// |===
 pub(crate) fn goto_type_definition(
     db: &RootDatabase,
     position: FilePosition,
diff --git a/crates/ra_ide/src/hover.rs b/crates/ra_ide/src/hover.rs
index 3e721dcca..d96cb5596 100644
--- a/crates/ra_ide/src/hover.rs
+++ b/crates/ra_ide/src/hover.rs
@@ -1,10 +1,10 @@
-//! Logic for computing info that is displayed when the user hovers over any
-//! source code items (e.g. function call, struct field, variable symbol...)
+use std::iter::once;
 
 use hir::{
     Adt, AsAssocItem, AssocItemContainer, FieldSource, HasSource, HirDisplay, ModuleDef,
     ModuleSource, Semantics,
 };
+use itertools::Itertools;
 use ra_db::SourceDatabase;
 use ra_ide_db::{
     defs::{classify_name, classify_name_ref, Definition},
@@ -21,8 +21,6 @@ use crate::{
     display::{macro_label, rust_code_markup, rust_code_markup_with_doc, ShortLabel},
     FilePosition, RangeInfo,
 };
-use itertools::Itertools;
-use std::iter::once;
 
 /// Contains the results when hovering over an item
 #[derive(Debug, Default)]
@@ -62,6 +60,63 @@ impl HoverResult {
     }
 }
 
+// Feature: Hover
+//
+// 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.
+pub(crate) fn hover(db: &RootDatabase, position: FilePosition) -> Option<RangeInfo<HoverResult>> {
+    let sema = Semantics::new(db);
+    let file = sema.parse(position.file_id).syntax().clone();
+    let token = pick_best(file.token_at_offset(position.offset))?;
+    let token = sema.descend_into_macros(token);
+
+    let mut res = HoverResult::new();
+
+    if let Some((node, name_kind)) = match_ast! {
+        match (token.parent()) {
+            ast::NameRef(name_ref) => {
+                classify_name_ref(&sema, &name_ref).map(|d| (name_ref.syntax().clone(), d.definition()))
+            },
+            ast::Name(name) => {
+                classify_name(&sema, &name).map(|d| (name.syntax().clone(), d.definition()))
+            },
+            _ => None,
+        }
+    } {
+        let range = sema.original_range(&node).range;
+        res.extend(hover_text_from_name_kind(db, name_kind));
+
+        if !res.is_empty() {
+            return Some(RangeInfo::new(range, res));
+        }
+    }
+
+    let node = token
+        .ancestors()
+        .find(|n| ast::Expr::cast(n.clone()).is_some() || ast::Pat::cast(n.clone()).is_some())?;
+
+    let ty = match_ast! {
+        match node {
+            ast::MacroCall(_it) => {
+                // If this node is a MACRO_CALL, it means that `descend_into_macros` failed to resolve.
+                // (e.g expanding a builtin macro). So we give up here.
+                return None;
+            },
+            ast::Expr(it) => {
+                sema.type_of_expr(&it)
+            },
+            ast::Pat(it) => {
+                sema.type_of_pat(&it)
+            },
+            _ => None,
+        }
+    }?;
+
+    res.extend(Some(rust_code_markup(&ty.display(db))));
+    let range = sema.original_range(&node).range;
+    Some(RangeInfo::new(range, res))
+}
+
 fn hover_text(
     docs: Option<String>,
     desc: Option<String>,
@@ -160,59 +215,6 @@ fn hover_text_from_name_kind(db: &RootDatabase, def: Definition) -> Option<Strin
     }
 }
 
-pub(crate) fn hover(db: &RootDatabase, position: FilePosition) -> Option<RangeInfo<HoverResult>> {
-    let sema = Semantics::new(db);
-    let file = sema.parse(position.file_id).syntax().clone();
-    let token = pick_best(file.token_at_offset(position.offset))?;
-    let token = sema.descend_into_macros(token);
-
-    let mut res = HoverResult::new();
-
-    if let Some((node, name_kind)) = match_ast! {
-        match (token.parent()) {
-            ast::NameRef(name_ref) => {
-                classify_name_ref(&sema, &name_ref).map(|d| (name_ref.syntax().clone(), d.definition()))
-            },
-            ast::Name(name) => {
-                classify_name(&sema, &name).map(|d| (name.syntax().clone(), d.definition()))
-            },
-            _ => None,
-        }
-    } {
-        let range = sema.original_range(&node).range;
-        res.extend(hover_text_from_name_kind(db, name_kind));
-
-        if !res.is_empty() {
-            return Some(RangeInfo::new(range, res));
-        }
-    }
-
-    let node = token
-        .ancestors()
-        .find(|n| ast::Expr::cast(n.clone()).is_some() || ast::Pat::cast(n.clone()).is_some())?;
-
-    let ty = match_ast! {
-        match node {
-            ast::MacroCall(_it) => {
-                // If this node is a MACRO_CALL, it means that `descend_into_macros` failed to resolve.
-                // (e.g expanding a builtin macro). So we give up here.
-                return None;
-            },
-            ast::Expr(it) => {
-                sema.type_of_expr(&it)
-            },
-            ast::Pat(it) => {
-                sema.type_of_pat(&it)
-            },
-            _ => None,
-        }
-    }?;
-
-    res.extend(Some(rust_code_markup(&ty.display(db))));
-    let range = sema.original_range(&node).range;
-    Some(RangeInfo::new(range, res))
-}
-
 fn pick_best(tokens: TokenAtOffset<SyntaxToken>) -> Option<SyntaxToken> {
     return tokens.max_by_key(priority);
     fn priority(n: &SyntaxToken) -> usize {
diff --git a/crates/ra_ide/src/inlay_hints.rs b/crates/ra_ide/src/inlay_hints.rs
index b391f903a..75bd3c96b 100644
--- a/crates/ra_ide/src/inlay_hints.rs
+++ b/crates/ra_ide/src/inlay_hints.rs
@@ -1,5 +1,3 @@
-//! This module defines multiple types of inlay hints and their visibility
-
 use hir::{Adt, HirDisplay, Semantics, Type};
 use ra_ide_db::RootDatabase;
 use ra_prof::profile;
@@ -39,6 +37,26 @@ pub struct InlayHint {
     pub label: SmolStr,
 }
 
+// Feature: Inlay Hints
+//
+// rust-analyzer shows additional information inline with the source code.
+// Editors usually render this using read-only virtual text snippets interspersed with code.
+//
+// rust-analyzer shows hits for
+//
+// * types of local variables
+// * names of function arguments
+// * types of chained expressions
+//
+// **Note:** VS Code does not have native support for inlay hints https://github.com/microsoft/vscode/issues/16221[yet] and the hints are implemented using decorations.
+// This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
+// https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.com/rust-analyzer/rust-analyzer/issues/3453[2].
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Toggle inlay hints*
+// |===
 pub(crate) fn inlay_hints(
     db: &RootDatabase,
     file_id: FileId,
diff --git a/crates/ra_ide/src/join_lines.rs b/crates/ra_ide/src/join_lines.rs
index af1ade8a1..5036c1fb0 100644
--- a/crates/ra_ide/src/join_lines.rs
+++ b/crates/ra_ide/src/join_lines.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use itertools::Itertools;
 use ra_fmt::{compute_ws, extract_trivial_expression};
 use ra_syntax::{
@@ -11,6 +9,15 @@ use ra_syntax::{
 };
 use ra_text_edit::{TextEdit, TextEditBuilder};
 
+// Feature: Join Lines
+//
+// Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Join lines**
+// |===
 pub fn join_lines(file: &SourceFile, range: TextRange) -> TextEdit {
     let range = if range.is_empty() {
         let syntax = file.syntax();
diff --git a/crates/ra_ide/src/lib.rs b/crates/ra_ide/src/lib.rs
index d983cd910..12d5716e8 100644
--- a/crates/ra_ide/src/lib.rs
+++ b/crates/ra_ide/src/lib.rs
@@ -23,6 +23,7 @@ mod completion;
 mod runnables;
 mod goto_definition;
 mod goto_type_definition;
+mod goto_implementation;
 mod extend_selection;
 mod hover;
 mod call_hierarchy;
@@ -30,7 +31,6 @@ mod call_info;
 mod syntax_highlighting;
 mod parent_module;
 mod references;
-mod impls;
 mod diagnostics;
 mod syntax_tree;
 mod folding_ranges;
@@ -373,7 +373,7 @@ impl Analysis {
         &self,
         position: FilePosition,
     ) -> Cancelable<Option<RangeInfo<Vec<NavigationTarget>>>> {
-        self.with_db(|db| impls::goto_implementation(db, position))
+        self.with_db(|db| goto_implementation::goto_implementation(db, position))
     }
 
     /// Returns the type definitions for the symbol at `position`.
diff --git a/crates/ra_ide/src/matching_brace.rs b/crates/ra_ide/src/matching_brace.rs
index b85348706..407a9636d 100644
--- a/crates/ra_ide/src/matching_brace.rs
+++ b/crates/ra_ide/src/matching_brace.rs
@@ -1,7 +1,16 @@
-//! FIXME: write short doc here
-
 use ra_syntax::{ast::AstNode, SourceFile, SyntaxKind, TextSize, T};
 
+// Feature: Matching Brace
+//
+// 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
+// braces, so it won't confuse generics with comparisons.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Find matching brace**
+// |===
 pub fn matching_brace(file: &SourceFile, offset: TextSize) -> Option<TextSize> {
     const BRACES: &[SyntaxKind] =
         &[T!['{'], T!['}'], T!['['], T![']'], T!['('], T![')'], T![<], T![>]];
diff --git a/crates/ra_ide/src/parent_module.rs b/crates/ra_ide/src/parent_module.rs
index a083fb1eb..fa1535da5 100644
--- a/crates/ra_ide/src/parent_module.rs
+++ b/crates/ra_ide/src/parent_module.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::Semantics;
 use ra_db::{CrateId, FileId, FilePosition};
 use ra_ide_db::RootDatabase;
@@ -11,6 +9,16 @@ use test_utils::mark;
 
 use crate::NavigationTarget;
 
+// Feature: Parent Module
+//
+// Navigates to the parent module of the current module.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Locate parent module**
+// |===
+
 /// This returns `Vec` because a module may be included from several places. We
 /// don't handle this case yet though, so the Vec has length at most one.
 pub(crate) fn parent_module(db: &RootDatabase, position: FilePosition) -> Vec<NavigationTarget> {
diff --git a/crates/ra_ide/src/references.rs b/crates/ra_ide/src/references.rs
index 96444bf6a..bb40d2043 100644
--- a/crates/ra_ide/src/references.rs
+++ b/crates/ra_ide/src/references.rs
@@ -615,6 +615,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_find_all_refs_nested_module() {
+        let code = r#"
+            //- /lib.rs
+            mod foo {
+                mod bar;
+            }
+
+            fn f<|>() {}
+
+            //- /foo/bar.rs
+            use crate::f;
+
+            fn g() {
+                f();
+            }
+        "#;
+
+        let (analysis, pos) = analysis_and_position(code);
+        let refs = analysis.find_all_refs(pos, None).unwrap().unwrap();
+        check_result(
+            refs,
+            "f FN_DEF FileId(1) 25..34 28..29 Other",
+            &["FileId(2) 11..12 Other", "FileId(2) 27..28 StructLiteral"],
+        );
+    }
+
     fn get_all_refs(text: &str) -> ReferenceSearchResult {
         let (analysis, position) = single_file_with_position(text);
         analysis.find_all_refs(position, None).unwrap().unwrap()
diff --git a/crates/ra_ide/src/runnables.rs b/crates/ra_ide/src/runnables.rs
index 6e7e47199..286d45eee 100644
--- a/crates/ra_ide/src/runnables.rs
+++ b/crates/ra_ide/src/runnables.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::{AsAssocItem, Attrs, HirFileId, InFile, Semantics};
 use itertools::Itertools;
 use ra_ide_db::RootDatabase;
@@ -44,6 +42,17 @@ pub enum RunnableKind {
     Bin,
 }
 
+// Feature: Run
+//
+// 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
+// to a shortcut!
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Run**
+// |===
 pub(crate) fn runnables(db: &RootDatabase, file_id: FileId) -> Vec<Runnable> {
     let sema = Semantics::new(db);
     let source_file = sema.parse(file_id);
diff --git a/crates/ra_ide/src/ssr.rs b/crates/ra_ide/src/ssr.rs
index 130d3b4c3..93e9aee1d 100644
--- a/crates/ra_ide/src/ssr.rs
+++ b/crates/ra_ide/src/ssr.rs
@@ -1,5 +1,3 @@
-//!  structural search replace
-
 use std::{collections::HashMap, iter::once, str::FromStr};
 
 use ra_db::{SourceDatabase, SourceDatabaseExt};
@@ -25,6 +23,28 @@ impl std::fmt::Display for SsrError {
 
 impl std::error::Error for SsrError {}
 
+// Feature: Structural Seach and Replace
+//
+// Search and replace with named wildcards that will match any expression.
+// The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`.
+// A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement.
+// Available via the command `rust-analyzer.ssr`.
+//
+// ```rust
+// // Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
+//
+// // BEFORE
+// String::from(foo(y + 5, z))
+//
+// // AFTER
+// String::from((y + 5).foo(z))
+// ```
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Structural Search Replace**
+// |===
 pub fn parse_search_replace(
     query: &str,
     parse_only: bool,
diff --git a/crates/ra_ide/src/status.rs b/crates/ra_ide/src/status.rs
index 30eb5c995..5b7992920 100644
--- a/crates/ra_ide/src/status.rs
+++ b/crates/ra_ide/src/status.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use std::{fmt, iter::FromIterator, sync::Arc};
 
 use hir::MacroFile;
@@ -26,6 +24,15 @@ fn macro_syntax_tree_stats(db: &RootDatabase) -> SyntaxTreeStats {
     db.query(hir::db::ParseMacroQuery).entries::<SyntaxTreeStats>()
 }
 
+// Feature: Status
+//
+// Shows internal statistic about memory usage of rust-analyzer.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Status**
+// |===
 pub(crate) fn status(db: &RootDatabase) -> String {
     let files_stats = db.query(FileTextQuery).entries::<FilesStats>();
     let syntax_tree_stats = syntax_tree_stats(db);
diff --git a/crates/ra_ide/src/syntax_highlighting.rs b/crates/ra_ide/src/syntax_highlighting.rs
index cd6464b40..0b53ebe69 100644
--- a/crates/ra_ide/src/syntax_highlighting.rs
+++ b/crates/ra_ide/src/syntax_highlighting.rs
@@ -1,5 +1,3 @@
-//! Implements syntax highlighting.
-
 mod tags;
 mod html;
 #[cfg(test)]
@@ -32,81 +30,15 @@ pub struct HighlightedRange {
     pub binding_hash: Option<u64>,
 }
 
-#[derive(Debug)]
-struct HighlightedRangeStack {
-    stack: Vec<Vec<HighlightedRange>>,
-}
-
-/// We use a stack to implement the flattening logic for the highlighted
-/// syntax ranges.
-impl HighlightedRangeStack {
-    fn new() -> Self {
-        Self { stack: vec![Vec::new()] }
-    }
-
-    fn push(&mut self) {
-        self.stack.push(Vec::new());
-    }
-
-    /// Flattens the highlighted ranges.
-    ///
-    /// For example `#[cfg(feature = "foo")]` contains the nested ranges:
-    /// 1) parent-range: Attribute [0, 23)
-    /// 2) child-range: String [16, 21)
-    ///
-    /// The following code implements the flattening, for our example this results to:
-    /// `[Attribute [0, 16), String [16, 21), Attribute [21, 23)]`
-    fn pop(&mut self) {
-        let children = self.stack.pop().unwrap();
-        let prev = self.stack.last_mut().unwrap();
-        let needs_flattening = !children.is_empty()
-            && !prev.is_empty()
-            && prev.last().unwrap().range.contains_range(children.first().unwrap().range);
-        if !needs_flattening {
-            prev.extend(children);
-        } else {
-            let mut parent = prev.pop().unwrap();
-            for ele in children {
-                assert!(parent.range.contains_range(ele.range));
-                let mut cloned = parent.clone();
-                parent.range = TextRange::new(parent.range.start(), ele.range.start());
-                cloned.range = TextRange::new(ele.range.end(), cloned.range.end());
-                if !parent.range.is_empty() {
-                    prev.push(parent);
-                }
-                prev.push(ele);
-                parent = cloned;
-            }
-            if !parent.range.is_empty() {
-                prev.push(parent);
-            }
-        }
-    }
-
-    fn add(&mut self, range: HighlightedRange) {
-        self.stack
-            .last_mut()
-            .expect("during DFS traversal, the stack must not be empty")
-            .push(range)
-    }
-
-    fn flattened(mut self) -> Vec<HighlightedRange> {
-        assert_eq!(
-            self.stack.len(),
-            1,
-            "after DFS traversal, the stack should only contain a single element"
-        );
-        let mut res = self.stack.pop().unwrap();
-        res.sort_by_key(|range| range.range.start());
-        // Check that ranges are sorted and disjoint
-        assert!(res
-            .iter()
-            .zip(res.iter().skip(1))
-            .all(|(left, right)| left.range.end() <= right.range.start()));
-        res
-    }
-}
-
+// Feature: Semantic Syntax Highlighting
+//
+// 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.
+// rust-analyzer does not specify colors directly, instead it assigns tag (like `struct`) and a set of modifiers (like `declaration`) to each token.
+// It's up to the client to map those to specific colors.
+//
+// The general rule is that a reference to an entity gets colored the same way as the entity itself.
+// We also give special modifier for `mut` and `&mut` local variables.
 pub(crate) fn highlight(
     db: &RootDatabase,
     file_id: FileId,
@@ -291,6 +223,81 @@ pub(crate) fn highlight(
     stack.flattened()
 }
 
+#[derive(Debug)]
+struct HighlightedRangeStack {
+    stack: Vec<Vec<HighlightedRange>>,
+}
+
+/// We use a stack to implement the flattening logic for the highlighted
+/// syntax ranges.
+impl HighlightedRangeStack {
+    fn new() -> Self {
+        Self { stack: vec![Vec::new()] }
+    }
+
+    fn push(&mut self) {
+        self.stack.push(Vec::new());
+    }
+
+    /// Flattens the highlighted ranges.
+    ///
+    /// For example `#[cfg(feature = "foo")]` contains the nested ranges:
+    /// 1) parent-range: Attribute [0, 23)
+    /// 2) child-range: String [16, 21)
+    ///
+    /// The following code implements the flattening, for our example this results to:
+    /// `[Attribute [0, 16), String [16, 21), Attribute [21, 23)]`
+    fn pop(&mut self) {
+        let children = self.stack.pop().unwrap();
+        let prev = self.stack.last_mut().unwrap();
+        let needs_flattening = !children.is_empty()
+            && !prev.is_empty()
+            && prev.last().unwrap().range.contains_range(children.first().unwrap().range);
+        if !needs_flattening {
+            prev.extend(children);
+        } else {
+            let mut parent = prev.pop().unwrap();
+            for ele in children {
+                assert!(parent.range.contains_range(ele.range));
+                let mut cloned = parent.clone();
+                parent.range = TextRange::new(parent.range.start(), ele.range.start());
+                cloned.range = TextRange::new(ele.range.end(), cloned.range.end());
+                if !parent.range.is_empty() {
+                    prev.push(parent);
+                }
+                prev.push(ele);
+                parent = cloned;
+            }
+            if !parent.range.is_empty() {
+                prev.push(parent);
+            }
+        }
+    }
+
+    fn add(&mut self, range: HighlightedRange) {
+        self.stack
+            .last_mut()
+            .expect("during DFS traversal, the stack must not be empty")
+            .push(range)
+    }
+
+    fn flattened(mut self) -> Vec<HighlightedRange> {
+        assert_eq!(
+            self.stack.len(),
+            1,
+            "after DFS traversal, the stack should only contain a single element"
+        );
+        let mut res = self.stack.pop().unwrap();
+        res.sort_by_key(|range| range.range.start());
+        // Check that ranges are sorted and disjoint
+        assert!(res
+            .iter()
+            .zip(res.iter().skip(1))
+            .all(|(left, right)| left.range.end() <= right.range.start()));
+        res
+    }
+}
+
 fn highlight_format_specifier(kind: FormatSpecifier) -> Option<HighlightTag> {
     Some(match kind {
         FormatSpecifier::Open
diff --git a/crates/ra_ide/src/syntax_tree.rs b/crates/ra_ide/src/syntax_tree.rs
index 86c70ff83..a341684fd 100644
--- a/crates/ra_ide/src/syntax_tree.rs
+++ b/crates/ra_ide/src/syntax_tree.rs
@@ -1,6 +1,4 @@
-//! FIXME: write short doc here
-
-use ra_db::SourceDatabase;
+use ra_db::{FileId, SourceDatabase};
 use ra_ide_db::RootDatabase;
 use ra_syntax::{
     algo, AstNode, NodeOrToken, SourceFile,
@@ -8,8 +6,16 @@ use ra_syntax::{
     SyntaxToken, TextRange, TextSize,
 };
 
-pub use ra_db::FileId;
-
+// Feature: Show Syntax Tree
+//
+// Shows the parse tree of the current file. It exists mostly for debugging
+// rust-analyzer itself.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Show Syntax Tree**
+// |===
 pub(crate) fn syntax_tree(
     db: &RootDatabase,
     file_id: FileId,
diff --git a/crates/ra_ide/src/typing.rs b/crates/ra_ide/src/typing.rs
index 39bb3b357..67e2c33a0 100644
--- a/crates/ra_ide/src/typing.rs
+++ b/crates/ra_ide/src/typing.rs
@@ -32,6 +32,13 @@ pub(crate) use on_enter::on_enter;
 
 pub(crate) const TRIGGER_CHARS: &str = ".=>";
 
+// Feature: On Typing Assists
+//
+// Some features trigger on typing certain characters:
+//
+// - typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
+// - Enter inside comments automatically inserts `///`
+// - typing `.` in a chain method call auto-indents
 pub(crate) fn on_char_typed(
     db: &RootDatabase,
     position: FilePosition,
diff --git a/crates/ra_ide_db/src/search.rs b/crates/ra_ide_db/src/search.rs
index 589f44771..335a1ad03 100644
--- a/crates/ra_ide_db/src/search.rs
+++ b/crates/ra_ide_db/src/search.rs
@@ -124,29 +124,33 @@ impl Definition {
 
         let vis = self.visibility(db);
 
-        // FIXME:
-        // The following logic are wrong that it does not search
-        // for submodules within other files recursively.
-
         if let Some(Visibility::Module(module)) = vis.and_then(|it| it.into()) {
             let module: Module = module.into();
             let mut res = FxHashMap::default();
-            let src = module.definition_source(db);
-            let file_id = src.file_id.original_file(db);
 
-            match src.value {
-                ModuleSource::Module(m) => {
-                    let range = Some(m.syntax().text_range());
-                    res.insert(file_id, range);
-                }
-                ModuleSource::SourceFile(_) => {
-                    res.insert(file_id, None);
-                    res.extend(module.children(db).map(|m| {
-                        let src = m.definition_source(db);
-                        (src.file_id.original_file(db), None)
-                    }));
-                }
+            let mut to_visit = vec![module];
+            let mut is_first = true;
+            while let Some(module) = to_visit.pop() {
+                let src = module.definition_source(db);
+                let file_id = src.file_id.original_file(db);
+                match src.value {
+                    ModuleSource::Module(m) => {
+                        if is_first {
+                            let range = Some(m.syntax().text_range());
+                            res.insert(file_id, range);
+                        } else {
+                            // We have already added the enclosing file to the search scope,
+                            // so do nothing.
+                        }
+                    }
+                    ModuleSource::SourceFile(_) => {
+                        res.insert(file_id, None);
+                    }
+                };
+                is_first = false;
+                to_visit.extend(module.children(db));
             }
+
             return SearchScope::new(res);
         }
 
diff --git a/crates/ra_ide_db/src/symbol_index.rs b/crates/ra_ide_db/src/symbol_index.rs
index 95be11134..acc31fe3b 100644
--- a/crates/ra_ide_db/src/symbol_index.rs
+++ b/crates/ra_ide_db/src/symbol_index.rs
@@ -110,6 +110,27 @@ fn file_symbols(db: &impl SymbolsDatabase, file_id: FileId) -> Arc<SymbolIndex>
     Arc::new(SymbolIndex::new(symbols))
 }
 
+// Feature: Workspace Symbol
+//
+// 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
+// navigation tremendously. It mostly works on top of the built-in LSP
+// functionality, however `#` and `*` symbols can be used to narrow down the
+// search. Specifically,
+//
+// - `Foo` searches for `Foo` type in the current workspace
+// - `foo#` searches for `foo` function in the current workspace
+// - `Foo*` searches for `Foo` type among dependencies, including `stdlib`
+// - `foo#*` searches for `foo` function among dependencies
+//
+// That is, `#` switches from "types" to all symbols, `*` switches from the current
+// workspace to dependencies.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+T]
+// |===
 pub fn world_symbols(db: &RootDatabase, query: Query) -> Vec<FileSymbol> {
     /// Need to wrap Snapshot to provide `Clone` impl for `map_with`
     struct Snap(salsa::Snapshot<RootDatabase>);
diff --git a/crates/ra_syntax/src/ast.rs b/crates/ra_syntax/src/ast.rs
index 1876afe95..eddc807d5 100644
--- a/crates/ra_syntax/src/ast.rs
+++ b/crates/ra_syntax/src/ast.rs
@@ -75,7 +75,7 @@ impl<N> AstChildren<N> {
 impl<N: AstNode> Iterator for AstChildren<N> {
     type Item = N;
     fn next(&mut self) -> Option<N> {
-        self.inner.by_ref().find_map(N::cast)
+        self.inner.find_map(N::cast)
     }
 }
 
diff --git a/crates/ra_syntax/src/ast/generated/nodes.rs b/crates/ra_syntax/src/ast/generated/nodes.rs
index 255402fbc..cb430ca01 100644
--- a/crates/ra_syntax/src/ast/generated/nodes.rs
+++ b/crates/ra_syntax/src/ast/generated/nodes.rs
@@ -1081,6 +1081,7 @@ pub struct BlockExpr {
 impl ast::AttrsOwner for BlockExpr {}
 impl ast::ModuleItemOwner for BlockExpr {}
 impl BlockExpr {
+    pub fn label(&self) -> Option<Label> { support::child(&self.syntax) }
     pub fn l_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T!['{']) }
     pub fn statements(&self) -> AstChildren<Stmt> { support::children(&self.syntax) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
diff --git a/crates/ra_syntax/src/syntax_node.rs b/crates/ra_syntax/src/syntax_node.rs
index e566af7e8..9650b8781 100644
--- a/crates/ra_syntax/src/syntax_node.rs
+++ b/crates/ra_syntax/src/syntax_node.rs
@@ -48,11 +48,11 @@ impl SyntaxTreeBuilder {
 
     pub fn finish(self) -> Parse<SyntaxNode> {
         let (green, errors) = self.finish_raw();
-        let node = SyntaxNode::new_root(green);
         if cfg!(debug_assertions) {
+            let node = SyntaxNode::new_root(green.clone());
             crate::validation::validate_block_structure(&node);
         }
-        Parse::new(node.green().clone(), errors)
+        Parse::new(green, errors)
     }
 
     pub fn token(&mut self, kind: SyntaxKind, text: SmolStr) {
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index d06da355d..b7237ee90 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -7,6 +7,16 @@ All capabilities are enabled via `experimental` field of `ClientCapabilities` or
 Requests which we hope to upstream live under `experimental/` namespace.
 Requests, which are likely to always remain specific to `rust-analyzer` are under `rust-analyzer/` namespace.
 
+If you want to be notified about the changes to this document, subscribe to [#4604](https://github.com/rust-analyzer/rust-analyzer/issues/4604).
+
+## `initializationOptions`
+
+As `initializationOptions`, `rust-analyzer` expects `"rust-analyzer"` section of the configuration.
+That is, `rust-analyzer` usually sends `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
+`initializationOptions` should contain the same data that would be in the first item of the result.
+It's OK to not send anything, then all the settings would take their default values.
+However, some settings can not be changed after startup at the moment.
+
 ## Snippet `TextEdit`
 
 **Issue:** https://github.com/microsoft/language-server-protocol/issues/724
diff --git a/docs/dev/lsp-features.md b/docs/dev/lsp-features.md
deleted file mode 100644
index 00b0867d7..000000000
--- a/docs/dev/lsp-features.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Supported LSP features
-
-This list documents LSP features, supported by rust-analyzer.
-
-## General
-- [x] [initialize](https://microsoft.github.io/language-server-protocol/specification#initialize)
-- [x] [initialized](https://microsoft.github.io/language-server-protocol/specification#initialized)
-- [x] [shutdown](https://microsoft.github.io/language-server-protocol/specification#shutdown)
-- [ ] [exit](https://microsoft.github.io/language-server-protocol/specification#exit)
-- [x] [$/cancelRequest](https://microsoft.github.io/language-server-protocol/specification#cancelRequest)
-
-## Workspace
-- [ ] [workspace/workspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_workspaceFolders)
-- [ ] [workspace/didChangeWorkspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWorkspaceFolders)
-- [x] [workspace/didChangeConfiguration](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeConfiguration)
-- [ ] [workspace/configuration](https://microsoft.github.io/language-server-protocol/specification#workspace_configuration)
-- [x] [workspace/didChangeWatchedFiles](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWatchedFiles)
-- [x] [workspace/symbol](https://microsoft.github.io/language-server-protocol/specification#workspace_symbol)
-- [ ] [workspace/applyEdit](https://microsoft.github.io/language-server-protocol/specification#workspace_applyEdit)
-
-## Text Synchronization
-- [x] [textDocument/didOpen](https://microsoft.github.io/language-server-protocol/specification#textDocument_didOpen)
-- [x] [textDocument/didChange](https://microsoft.github.io/language-server-protocol/specification#textDocument_didChange)
-- [ ] [textDocument/willSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSave)
-- [ ] [textDocument/willSaveWaitUntil](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSaveWaitUntil)
-- [x] [textDocument/didSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_didSave)
-- [x] [textDocument/didClose](https://microsoft.github.io/language-server-protocol/specification#textDocument_didClose)
-
-## Diagnostics
-- [x] [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics)
-
-## Lanuguage Features
-- [x] [textDocument/completion](https://microsoft.github.io/language-server-protocol/specification#textDocument_completion)
- - open close: false
- - change: Full
- - will save: false
- - will save wait until: false
- - save: false
-- [x] [completionItem/resolve](https://microsoft.github.io/language-server-protocol/specification#completionItem_resolve)
- - resolve provider: none
- - trigger characters: `:`, `.`
-- [x] [textDocument/hover](https://microsoft.github.io/language-server-protocol/specification#textDocument_hover)
-- [x] [textDocument/signatureHelp](https://microsoft.github.io/language-server-protocol/specification#textDocument_signatureHelp)
- - trigger characters: `(`,  `,`
-- [ ] [textDocument/declaration](https://microsoft.github.io/language-server-protocol/specification#textDocument_declaration)
-- [x] [textDocument/definition](https://microsoft.github.io/language-server-protocol/specification#textDocument_definition)
-- [x] [textDocument/typeDefinition](https://microsoft.github.io/language-server-protocol/specification#textDocument_typeDefinition)
-- [x] [textDocument/implementation](https://microsoft.github.io/language-server-protocol/specification#textDocument_implementation)
-- [x] [textDocument/references](https://microsoft.github.io/language-server-protocol/specification#textDocument_references)
-- [x] [textDocument/documentHighlight](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight)
-- [x] [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol)
-- [x] [textDocument/codeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction)
-- [x] [textDocument/selectionRange](https://github.com/Microsoft/language-server-protocol/issues/613)
- - rust-analyzer.syntaxTree
- - rust-analyzer.matchingBrace
- - rust-analyzer.parentModule
- - rust-analyzer.joinLines
- - rust-analyzer.run
- - rust-analyzer.analyzerStatus
-- [x] [textDocument/codeLens](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeLens)
-- [x] [codeLens/resolve](https://microsoft.github.io/language-server-protocol/specification#codeLens_resolve)
-- [ ] [documentLink/resolve](https://microsoft.github.io/language-server-protocol/specification#documentLink_resolve)
-- [ ] [textDocument/documentColor](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor)
-- [ ] [textDocument/colorPresentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation)
-- [x] [textDocument/formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting)
-- [ ] [textDocument/rangeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting)
-- [x] [textDocument/onTypeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_onTypeFormatting)
- - first trigger character: `=`
- - more trigger character `.`
-- [x] [textDocument/rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_rename)
-- [x] [textDocument/prepareRename](https://microsoft.github.io/language-server-protocol/specification#textDocument_prepareRename)
-- [x] [textDocument/foldingRange](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange)
diff --git a/docs/user/features.md b/docs/user/features.md
deleted file mode 100644
index 12ecdec13..000000000
--- a/docs/user/features.md
+++ /dev/null
@@ -1,218 +0,0 @@
-This document is an index of features that the rust-analyzer language server
-provides. Shortcuts are for the default VS Code layout. If there's no shortcut,
-you can use <kbd>Ctrl+Shift+P</kbd> to search for the corresponding action.
-
-### Workspace Symbol <kbd>ctrl+t</kbd>
-
-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
-navigation tremendously. It mostly works on top of the built-in LSP
-functionality, however `#` and `*` symbols can be used to narrow down the
-search. Specifically,
-
-- `Foo` searches for `Foo` type in the current workspace
-- `foo#` searches for `foo` function in the current workspace
-- `Foo*` searches for `Foo` type among dependencies, including `stdlib`
-- `foo#*` searches for `foo` function among dependencies
-
-That is, `#` switches from "types" to all symbols, `*` switches from the current
-workspace to dependencies.
-
-### Document Symbol <kbd>ctrl+shift+o</kbd>
-
-Provides a tree of the symbols defined in the file. Can be used to
-
-* fuzzy search symbol in a file (super useful)
-* draw breadcrumbs to describe the context around the cursor
-* draw outline of the file
-
-### On Typing Assists
-
-Some features trigger on typing certain characters:
-
-- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
-- Enter inside comments automatically inserts `///`
-- typing `.` in a chain method call auto-indents
-
-### Extend Selection
-
-Extends the current selection to the encompassing syntactic construct
-(expression, statement, item, module, etc). It works with multiple cursors. This
-is a relatively new feature of LSP:
-https://github.com/Microsoft/language-server-protocol/issues/613, check your
-editor's LSP library to see if this feature is supported.
-
-### Go to Definition
-
-Navigates to the definition of an identifier.
-
-### Go to Implementation
-
-Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
-
-### Go to Type Defintion
-
-Navigates to the type of an identifier.
-
-### Commands <kbd>ctrl+shift+p</kbd>
-
-#### Run
-
-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
-to a shortcut!
-
-#### Parent Module
-
-Navigates to the parent module of the current module.
-
-#### Matching Brace
-
-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
-braces, so it won't confuse generics with comparisons.
-
-#### Join Lines
-
-Join selected lines into one, smartly fixing up whitespace and trailing commas.
-
-#### Show Syntax Tree
-
-Shows the parse tree of the current file. It exists mostly for debugging
-rust-analyzer itself.
-
-#### Expand Macro Recursively
-
-Shows the full macro expansion of the macro at current cursor.
-
-#### Status
-
-Shows internal statistic about memory usage of rust-analyzer.
-
-#### Show RA Version
-
-Show current rust-analyzer version.
-
-#### Toggle inlay hints
-
-Toggle inlay hints view for the current workspace.
-It is recommended to assign a shortcut for this command to quickly turn off
-inlay hints when they prevent you from reading/writing the code.
-
-#### Run Garbage Collection
-
-Manually triggers GC.
-
-#### Start Cargo Watch
-
-Start `cargo watch` for live error highlighting. Will prompt to install if it's not already installed.
-
-#### Stop Cargo Watch
-
-Stop `cargo watch`.
-
-#### Structural Seach and Replace
-
-Search and replace with named wildcards that will match any expression.
-The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`. A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement. Available via the command `rust-analyzer.ssr`.
-
-```rust
-// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
-
-// BEFORE
-String::from(foo(y + 5, z))
-
-// AFTER
-String::from((y + 5).foo(z))
-```
-
-### Assists (Code Actions)
-
-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.
-
-See [assists.md](./assists.md) for the list of available assists.
-
-### Magic Completions
-
-In addition to usual reference completion, rust-analyzer provides some ✨magic✨
-completions as well:
-
-Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
-is placed at the appropriate position. Even though `if` is easy to type, you
-still want to complete it, to get ` { }` for free! `return` is inserted with a
-space or `;` depending on the return type of the function.
-
-When completing a function call, `()` are automatically inserted. If a function
-takes arguments, the cursor is positioned inside the parenthesis.
-
-There are postfix completions, which can be triggered by typing something like
-`foo().if`. The word after `.` determines postfix completion. Possible variants are:
-
-- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
-- `expr.match` -> `match expr {}`
-- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
-- `expr.ref` -> `&expr`
-- `expr.refm` -> `&mut expr`
-- `expr.not` -> `!expr`
-- `expr.dbg` -> `dbg!(expr)`
-
-There also snippet completions:
-
-#### Inside Expressions
-
-- `pd` -> `println!("{:?}")`
-- `ppd` -> `println!("{:#?}")`
-
-#### Inside Modules
-
-- `tfn` -> `#[test] fn f(){}`
-- `tmod` ->
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_fn() {}
-}
-```
-
-### Code Highlighting
-
-Experimental feature to let rust-analyzer highlight Rust code instead of using the
-default highlighter.
-
-#### Rainbow Highlighting
-
-Experimental feature that, given code highlighting using rust-analyzer is
-active, will pick unique colors for identifiers.
-
-### Code hints
-
-Rust-analyzer has two types of hints to show the information about the code:
-
-* hover hints, appearing on hover on any element.
-
-These contain extended information on the hovered language item.
-
-* inlay hints, shown near the element hinted directly in the editor.
-
-Two types of inlay hints are displayed currently:
-
-* type hints, displaying the minimal information on the type of the expression (if the information is available)
-* method chaining hints, type information for multi-line method chains
-* parameter name hints, displaying the names of the parameters in the corresponding methods
-
-#### VS Code
-
-In VS Code, the following settings can be used to configure the inlay hints:
-
-* `rust-analyzer.inlayHints.typeHints` - enable hints for inferred types.
-* `rust-analyzer.inlayHints.chainingHints` - enable hints for inferred types on method chains.
-* `rust-analyzer.inlayHints.parameterHints` - enable hints for function parameters.
-* `rust-analyzer.inlayHints.maxLength` — shortens the hints if their length exceeds the value specified. If no value is specified (`null`), no shortening is applied.
-
-**Note:** VS Code does not have native support for inlay hints [yet](https://github.com/microsoft/vscode/issues/16221) and the hints are implemented using decorations.
-This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
-[1](https://github.com/rust-analyzer/rust-analyzer/issues/1623), [2](https://github.com/rust-analyzer/rust-analyzer/issues/3453).
diff --git a/docs/user/assists.md b/docs/user/generated_assists.adoc
index a1058ecde..4d2fb31d4 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,36 +44,69 @@ 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_function`
+
+[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
+enum A { ┃One(u32) }
+```
+
+.After
+```rust
+enum A { One(u32) }
+
+impl From<u32> for A {
+    fn from(v: u32) -> Self {
+        A::One(v)
+    }
+}
+```
+
+
+[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() {
@@ -82,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,
 }
@@ -118,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);
@@ -135,8 +185,10 @@ impl Trait for () {
     fn foo(&self) {}┃
 
 }
+```
 
-// AFTER
+.After
+```rust
 trait Trait {
     Type X;
     fn foo(&self);
@@ -151,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;
@@ -166,8 +221,10 @@ trait Trait<T> {
 impl Trait<u32> for () {┃
 
 }
+```
 
-// AFTER
+.After
+```rust
 trait Trait<T> {
     Type X;
     fn foo(&self) -> T;
@@ -182,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,
 }
@@ -203,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)`.
@@ -229,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() {
@@ -259,68 +336,59 @@ fn main() {
 }
 ```
 
-## `change_lifetime_anon_to_named`
-
-Change an anonymous lifetime to a named lifetime.
-
-```rust
-// BEFORE
-impl Cursor<'_┃> {
-    fn node(self) -> &SyntaxNode {
-        match self {
-            Cursor::Replace(node) | Cursor::Before(node) => node,
-        }
-    }
-}
-
-// AFTER
-impl<'a> Cursor<'a> {
-    fn node(self) -> &SyntaxNode {
-        match self {
-            Cursor::Replace(node) | Cursor::Before(node) => node,
-        }
-    }
-}
-```
 
-## `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;
@@ -330,12 +398,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) {
@@ -343,8 +414,10 @@ fn handle(action: Action) {
         ┃
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -355,20 +428,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() {}
 }
@@ -377,154 +455,231 @@ 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_named_lifetime`
+**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/introduce_named_lifetime.rs#L12[introduce_named_lifetime.rs]
+
+Change an anonymous lifetime to a named lifetime.
+
+.Before
+```rust
+impl Cursor<'_┃> {
+    fn node(self) -> &SyntaxNode {
+        match self {
+            Cursor::Replace(node) | Cursor::Before(node) => node,
+        }
+    }
+}
+```
+
+.After
+```rust
+impl<'a> Cursor<'a> {
+    fn node(self) -> &SyntaxNode {
+        match self {
+            Cursor::Replace(node) | Cursor::Before(node) => node,
+        }
+    }
+}
+```
+
+
+[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) {
@@ -533,8 +688,10 @@ fn handle(action: Action) {
         Action::Stop => foo(),
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -544,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) {
@@ -558,8 +718,10 @@ fn handle(action: Action) {
         _ => (),
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -570,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) {
@@ -600,8 +770,10 @@ fn handle(action: Action) {
         _ => (),
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -612,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) {
@@ -690,8 +885,10 @@ fn handle(action: Action) {
         bar()
     }
 }
+```
 
-// AFTER
+.After
+```rust
 enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
@@ -702,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() {
@@ -725,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);
@@ -762,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
new file mode 100644
index 000000000..12812fa0b
--- /dev/null
+++ b/docs/user/generated_features.adoc
@@ -0,0 +1,298 @@
+=== Expand Macro Recursively
+**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.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Expand macro recursively**
+|===
+
+
+=== Extend Selection
+**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.
+
+|===
+| Editor  | Shortcut
+
+| VS Code | kbd:[Ctrl+Shift+→]
+|===
+
+
+=== File Structure
+**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
+
+* fuzzy search symbol in a file (super useful)
+* draw breadcrumbs to describe the context around the cursor
+* draw outline of the file
+
+|===
+| Editor  | Shortcut
+
+| VS Code | kbd:[Ctrl+Shift+O]
+|===
+
+
+=== Go to Definition
+**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.
+
+|===
+| Editor  | Shortcut
+
+| VS Code | kbd:[F12]
+|===
+
+
+=== Go to Implementation
+**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.
+
+|===
+| Editor  | Shortcut
+
+| VS Code | kbd:[Ctrl+F12]
+|===
+
+
+=== Go to Type Definition
+**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.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Go to Type Definition*
+|===
+
+
+=== Hover
+**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#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.
+
+rust-analyzer shows hits for
+
+* types of local variables
+* names of function arguments
+* types of chained expressions
+
+**Note:** VS Code does not have native support for inlay hints https://github.com/microsoft/vscode/issues/16221[yet] and the hints are implemented using decorations.
+This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
+https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.com/rust-analyzer/rust-analyzer/issues/3453[2].
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Toggle inlay hints*
+|===
+
+
+=== Join Lines
+**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.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Join lines**
+|===
+
+
+=== Magic Completions
+**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:
+
+Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
+is placed at the appropriate position. Even though `if` is easy to type, you
+still want to complete it, to get ` { }` for free! `return` is inserted with a
+space or `;` depending on the return type of the function.
+
+When completing a function call, `()` are automatically inserted. If a function
+takes arguments, the cursor is positioned inside the parenthesis.
+
+There are postfix completions, which can be triggered by typing something like
+`foo().if`. The word after `.` determines postfix completion. Possible variants are:
+
+- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
+- `expr.match` -> `match expr {}`
+- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
+- `expr.ref` -> `&expr`
+- `expr.refm` -> `&mut expr`
+- `expr.not` -> `!expr`
+- `expr.dbg` -> `dbg!(expr)`
+
+There also snippet completions:
+
+.Expressions
+- `pd` -> `println!("{:?}")`
+- `ppd` -> `println!("{:#?}")`
+
+.Items
+- `tfn` -> `#[test] fn f(){}`
+- `tmod` ->
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_fn() {}
+}
+```
+
+
+=== Matching Brace
+**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
+braces, so it won't confuse generics with comparisons.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Find matching brace**
+|===
+
+
+=== On Typing Assists
+**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:
+
+- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
+- Enter inside comments automatically inserts `///`
+- typing `.` in a chain method call auto-indents
+
+
+=== Parent Module
+**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.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Locate parent module**
+|===
+
+
+=== Run
+**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
+to a shortcut!
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Run**
+|===
+
+
+=== Semantic Syntax Highlighting
+**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.
+rust-analyzer does not specify colors directly, instead it assigns tag (like `struct`) and a set of modifiers (like `declaration`) to each token.
+It's up to the client to map those to specific colors.
+
+The general rule is that a reference to an entity gets colored the same way as the entity itself.
+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#L9[syntax_tree.rs]
+
+Shows the parse tree of the current file. It exists mostly for debugging
+rust-analyzer itself.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Show Syntax Tree**
+|===
+
+
+=== Status
+**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.
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Status**
+|===
+
+
+=== Structural Seach and Replace
+**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>`.
+A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement.
+Available via the command `rust-analyzer.ssr`.
+
+```rust
+// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
+
+// BEFORE
+String::from(foo(y + 5, z))
+
+// AFTER
+String::from((y + 5).foo(z))
+```
+
+|===
+| Editor  | Action Name
+
+| VS Code | **Rust Analyzer: Structural Search Replace**
+|===
+
+
+=== Workspace Symbol
+**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
+navigation tremendously. It mostly works on top of the built-in LSP
+functionality, however `#` and `*` symbols can be used to narrow down the
+search. Specifically,
+
+- `Foo` searches for `Foo` type in the current workspace
+- `foo#` searches for `foo` function in the current workspace
+- `Foo*` searches for `Foo` type among dependencies, including `stdlib`
+- `foo#*` searches for `foo` function among dependencies
+
+That is, `#` switches from "types" to all symbols, `*` switches from the current
+workspace to dependencies.
+
+|===
+| Editor  | Shortcut
+
+| VS Code | kbd:[Ctrl+T]
+|===
diff --git a/docs/user/readme.adoc b/docs/user/manual.adoc
index 64bd0feb1..202783fd9 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/manual.adoc
@@ -2,12 +2,9 @@
 :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:
 
 // Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
 
@@ -17,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.
 
@@ -65,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.
@@ -122,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
 
@@ -145,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
 
@@ -268,6 +269,14 @@ Gnome Builder currently has support for RLS, and there's no way to configure the
 1. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`).
 2. Enable the Rust Builder plugin.
 
-== Usage
+== Features
+
+include::./generated_features.adoc[]
+
+== Assists (Code Actions)
+
+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 https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md].
+include::./generated_assists.adoc[]
diff --git a/editors/code/src/run.ts b/editors/code/src/run.ts
index 401cb76af..113354bab 100644
--- a/editors/code/src/run.ts
+++ b/editors/code/src/run.ts
@@ -178,7 +178,7 @@ export function createTask(spec: ra.Runnable): vscode.Task {
         label: spec.label,
         command: toolchain.getPathForExecutable(spec.kind),
         args: spec.extraArgs ? [...spec.args, '--', ...spec.extraArgs] : spec.args,
-        env: spec.env,
+        env: Object.assign({}, process.env, spec.env),
     };
 
     const execOption: vscode.ShellExecutionOptions = {
diff --git a/xtask/src/ast_src.rs b/xtask/src/ast_src.rs
index d4621930e..f60f0fb16 100644
--- a/xtask/src/ast_src.rs
+++ b/xtask/src/ast_src.rs
@@ -1058,7 +1058,7 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
         /// [Reference](https://doc.rust-lang.org/reference/expressions/block-expr.html)
         /// [Labels for blocks RFC](https://github.com/rust-lang/rfcs/blob/master/text/2046-label-break-value.md)
         struct BlockExpr: AttrsOwner, ModuleItemOwner {
-            T!['{'], statements: [Stmt], Expr, T!['}'],
+            Label, T!['{'], statements: [Stmt], Expr, T!['}'],
         }
 
         /// Return expression.
diff --git a/xtask/src/codegen.rs b/xtask/src/codegen.rs
index b4907f4b2..5511c01d5 100644
--- a/xtask/src/codegen.rs
+++ b/xtask/src/codegen.rs
@@ -8,14 +8,18 @@
 mod gen_syntax;
 mod gen_parser_tests;
 mod gen_assists_docs;
+mod gen_feature_docs;
 
-use std::{mem, path::Path};
+use std::{
+    fmt, mem,
+    path::{Path, PathBuf},
+};
 
-use crate::{not_bash::fs2, Result};
+use crate::{not_bash::fs2, project_root, Result};
 
 pub use self::{
-    gen_assists_docs::generate_assists_docs, gen_parser_tests::generate_parser_tests,
-    gen_syntax::generate_syntax,
+    gen_assists_docs::generate_assists_docs, gen_feature_docs::generate_feature_docs,
+    gen_parser_tests::generate_parser_tests, gen_syntax::generate_syntax,
 };
 
 const GRAMMAR_DIR: &str = "crates/ra_parser/src/grammar";
@@ -28,7 +32,6 @@ const AST_TOKENS: &str = "crates/ra_syntax/src/ast/generated/tokens.rs";
 
 const ASSISTS_DIR: &str = "crates/ra_assists/src/handlers";
 const ASSISTS_TESTS: &str = "crates/ra_assists/src/tests/generated.rs";
-const ASSISTS_DOCS: &str = "docs/user/assists.md";
 
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum Mode {
@@ -40,7 +43,7 @@ pub enum Mode {
 /// With verify = false,
 fn update(path: &Path, contents: &str, mode: Mode) -> Result<()> {
     match fs2::read_to_string(path) {
-        Ok(ref old_contents) if normalize(old_contents) == normalize(contents) => {
+        Ok(old_contents) if normalize(&old_contents) == normalize(contents) => {
             return Ok(());
         }
         _ => (),
@@ -58,35 +61,85 @@ fn update(path: &Path, contents: &str, mode: Mode) -> Result<()> {
 }
 
 fn extract_comment_blocks(text: &str) -> Vec<Vec<String>> {
-    do_extract_comment_blocks(text, false)
+    do_extract_comment_blocks(text, false).into_iter().map(|(_line, block)| block).collect()
+}
+
+fn extract_comment_blocks_with_empty_lines(tag: &str, text: &str) -> Vec<CommentBlock> {
+    assert!(tag.starts_with(char::is_uppercase));
+    let tag = format!("{}:", tag);
+    let mut res = Vec::new();
+    for (line, mut block) in do_extract_comment_blocks(text, true) {
+        let first = block.remove(0);
+        if first.starts_with(&tag) {
+            let id = first[tag.len()..].trim().to_string();
+            let block = CommentBlock { id, line, contents: block };
+            res.push(block);
+        }
+    }
+    res
 }
 
-fn extract_comment_blocks_with_empty_lines(text: &str) -> Vec<Vec<String>> {
-    do_extract_comment_blocks(text, true)
+struct CommentBlock {
+    id: String,
+    line: usize,
+    contents: Vec<String>,
 }
 
-fn do_extract_comment_blocks(text: &str, allow_blocks_with_empty_lines: bool) -> Vec<Vec<String>> {
+fn do_extract_comment_blocks(
+    text: &str,
+    allow_blocks_with_empty_lines: bool,
+) -> Vec<(usize, Vec<String>)> {
     let mut res = Vec::new();
 
     let prefix = "// ";
     let lines = text.lines().map(str::trim_start);
 
-    let mut block = vec![];
-    for line in lines {
+    let mut block = (0, vec![]);
+    for (line_num, line) in lines.enumerate() {
         if line == "//" && allow_blocks_with_empty_lines {
-            block.push(String::new());
+            block.1.push(String::new());
             continue;
         }
 
         let is_comment = line.starts_with(prefix);
         if is_comment {
-            block.push(line[prefix.len()..].to_string());
-        } else if !block.is_empty() {
-            res.push(mem::replace(&mut block, Vec::new()));
+            block.1.push(line[prefix.len()..].to_string());
+        } else {
+            if !block.1.is_empty() {
+                res.push(mem::take(&mut block));
+            }
+            block.0 = line_num + 2;
         }
     }
-    if !block.is_empty() {
-        res.push(mem::replace(&mut block, Vec::new()))
+    if !block.1.is_empty() {
+        res.push(block)
     }
     res
 }
+
+#[derive(Debug)]
+struct Location {
+    file: PathBuf,
+    line: usize,
+}
+
+impl Location {
+    fn new(file: PathBuf, line: usize) -> Self {
+        Self { file, line }
+    }
+}
+
+impl fmt::Display for Location {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let path = self.file.strip_prefix(&project_root()).unwrap().display().to_string();
+        let path = path.replace('\\', "/");
+        let name = self.file.file_name().unwrap();
+        write!(
+            f,
+            "https://github.com/rust-analyzer/rust-analyzer/blob/master/{}#L{}[{}]",
+            path,
+            self.line,
+            name.to_str().unwrap()
+        )
+    }
+}
diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs
index 20dcde820..6c1be5350 100644
--- a/xtask/src/codegen/gen_assists_docs.rs
+++ b/xtask/src/codegen/gen_assists_docs.rs
@@ -1,22 +1,28 @@
 //! Generates `assists.md` documentation.
 
-use std::{fs, path::Path};
+use std::{fmt, fs, path::Path};
 
 use crate::{
-    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
     project_root, rust_files, Result,
 };
 
 pub fn generate_assists_docs(mode: Mode) -> Result<()> {
     let assists = Assist::collect()?;
     generate_tests(&assists, mode)?;
-    generate_docs(&assists, mode)?;
+
+    let contents = assists.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_assists.adoc");
+    codegen::update(&dst, &contents, mode)?;
+
     Ok(())
 }
 
 #[derive(Debug)]
 struct Assist {
     id: String,
+    location: Location,
     doc: String,
     before: String,
     after: String,
@@ -33,22 +39,18 @@ impl Assist {
 
         fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
             let text = fs::read_to_string(path)?;
-            let comment_blocks = extract_comment_blocks_with_empty_lines(&text);
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Assist", &text);
 
             for block in comment_blocks {
                 // FIXME: doesn't support blank lines yet, need to tweak
                 // `extract_comment_blocks` for that.
-                let mut lines = block.iter();
-                let first_line = lines.next().unwrap();
-                if !first_line.starts_with("Assist: ") {
-                    continue;
-                }
-                let id = first_line["Assist: ".len()..].to_string();
+                let id = block.id;
                 assert!(
                     id.chars().all(|it| it.is_ascii_lowercase() || it == '_'),
                     "invalid assist id: {:?}",
                     id
                 );
+                let mut lines = block.contents.iter();
 
                 let doc = take_until(lines.by_ref(), "```").trim().to_string();
                 assert!(
@@ -62,7 +64,8 @@ impl Assist {
                 assert_eq!(lines.next().unwrap().as_str(), "->");
                 assert_eq!(lines.next().unwrap().as_str(), "```");
                 let after = take_until(lines.by_ref(), "```");
-                acc.push(Assist { id, doc, before, after })
+                let location = Location::new(path.to_path_buf(), block.line);
+                acc.push(Assist { id, location, doc, before, after })
             }
 
             fn take_until<'a>(lines: impl Iterator<Item = &'a String>, marker: &str) -> String {
@@ -80,6 +83,33 @@ impl Assist {
     }
 }
 
+impl fmt::Display for Assist {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let before = self.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
+        let after = self.after.replace("<|>", "┃");
+        writeln!(
+            f,
+            "[discrete]\n=== `{}`
+**Source:** {}
+
+{}
+
+.Before
+```rust
+{}```
+
+.After
+```rust
+{}```",
+            self.id,
+            self.location,
+            self.doc,
+            hide_hash_comments(&before),
+            hide_hash_comments(&after)
+        )
+    }
+}
+
 fn generate_tests(assists: &[Assist], mode: Mode) -> Result<()> {
     let mut buf = String::from("use super::check_doc_test;\n");
 
@@ -107,37 +137,6 @@ r#####"
     codegen::update(&project_root().join(codegen::ASSISTS_TESTS), &buf, mode)
 }
 
-fn generate_docs(assists: &[Assist], mode: Mode) -> Result<()> {
-    let mut buf = String::from(
-        "# Assists\n\nCursor position or selection is signified by `┃` character.\n\n",
-    );
-
-    for assist in assists {
-        let before = assist.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
-        let after = assist.after.replace("<|>", "┃");
-        let docs = format!(
-            "
-## `{}`
-
-{}
-
-```rust
-// BEFORE
-{}
-// AFTER
-{}```
-",
-            assist.id,
-            assist.doc,
-            hide_hash_comments(&before),
-            hide_hash_comments(&after)
-        );
-        buf.push_str(&docs);
-    }
-
-    codegen::update(&project_root().join(codegen::ASSISTS_DOCS), &buf, mode)
-}
-
 fn hide_hash_comments(text: &str) -> String {
     text.split('\n') // want final newline
         .filter(|&it| !(it.starts_with("# ") || it == "#"))
diff --git a/xtask/src/codegen/gen_feature_docs.rs b/xtask/src/codegen/gen_feature_docs.rs
new file mode 100644
index 000000000..31bc3839d
--- /dev/null
+++ b/xtask/src/codegen/gen_feature_docs.rs
@@ -0,0 +1,75 @@
+//! Generates `assists.md` documentation.
+
+use std::{fmt, fs, path::PathBuf};
+
+use crate::{
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
+    project_root, rust_files, Result,
+};
+
+pub fn generate_feature_docs(mode: Mode) -> Result<()> {
+    let features = Feature::collect()?;
+    let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_features.adoc");
+    codegen::update(&dst, &contents, mode)?;
+    Ok(())
+}
+
+#[derive(Debug)]
+struct Feature {
+    id: String,
+    location: Location,
+    doc: String,
+}
+
+impl Feature {
+    fn collect() -> Result<Vec<Feature>> {
+        let mut res = Vec::new();
+        for path in rust_files(&project_root()) {
+            collect_file(&mut res, path)?;
+        }
+        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
+        return Ok(res);
+
+        fn collect_file(acc: &mut Vec<Feature>, path: PathBuf) -> Result<()> {
+            let text = fs::read_to_string(&path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text);
+
+            for block in comment_blocks {
+                let id = block.id;
+                assert!(is_valid_feature_name(&id), "invalid feature name: {:?}", id);
+                let doc = block.contents.join("\n");
+                let location = Location::new(path.clone(), block.line);
+                acc.push(Feature { id, location, doc })
+            }
+
+            Ok(())
+        }
+    }
+}
+
+fn is_valid_feature_name(feature: &str) -> bool {
+    'word: for word in feature.split_whitespace() {
+        for &short in ["to", "and"].iter() {
+            if word == short {
+                continue 'word;
+            }
+        }
+        for &short in ["To", "And"].iter() {
+            if word == short {
+                return false;
+            }
+        }
+        if !word.starts_with(char::is_uppercase) {
+            return false;
+        }
+    }
+    true
+}
+
+impl fmt::Display for Feature {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
+    }
+}
diff --git a/xtask/src/lib.rs b/xtask/src/lib.rs
index 2b7a461e5..874957885 100644
--- a/xtask/src/lib.rs
+++ b/xtask/src/lib.rs
@@ -191,7 +191,11 @@ Release: release:{}[]
     let path = changelog_dir.join(format!("{}-changelog-{}.adoc", today, changelog_n));
     fs2::write(&path, &contents)?;
 
-    fs2::copy(project_root().join("./docs/user/readme.adoc"), website_root.join("manual.adoc"))?;
+    for &adoc in ["manual.adoc", "generated_features.adoc", "generated_assists.adoc"].iter() {
+        let src = project_root().join("./docs/user/").join(adoc);
+        let dst = website_root.join(adoc);
+        fs2::copy(src, dst)?;
+    }
 
     let tags = run!("git tag --list"; echo = false)?;
     let prev_tag = tags.lines().filter(|line| is_release_tag(line)).last().unwrap();
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index dff3ce4a1..9d7cdd114 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -75,6 +75,7 @@ FLAGS:
             codegen::generate_syntax(Mode::Overwrite)?;
             codegen::generate_parser_tests(Mode::Overwrite)?;
             codegen::generate_assists_docs(Mode::Overwrite)?;
+            codegen::generate_feature_docs(Mode::Overwrite)?;
             Ok(())
         }
         "format" => {
diff --git a/xtask/tests/tidy.rs b/xtask/tests/tidy.rs
index 2e9fcf07c..4ac5d929f 100644
--- a/xtask/tests/tidy.rs
+++ b/xtask/tests/tidy.rs
@@ -31,6 +31,13 @@ fn generated_assists_are_fresh() {
 }
 
 #[test]
+fn generated_features_are_fresh() {
+    if let Err(error) = codegen::generate_feature_docs(Mode::Verify) {
+        panic!("{}. Please update features by running `cargo xtask codegen`", error);
+    }
+}
+
+#[test]
 fn check_code_formatting() {
     if let Err(error) = run_rustfmt(Mode::Verify) {
         panic!("{}. Please format the code by running `cargo format`", error);
@@ -95,7 +102,7 @@ impl TidyDocs {
     fn visit(&mut self, path: &Path, text: &str) {
         // Test hopefully don't really need comments, and for assists we already
         // have special comments which are source of doc tests and user docs.
-        if is_exclude_dir(path, &["tests", "test_data", "handlers"]) {
+        if is_exclude_dir(path, &["tests", "test_data"]) {
             return;
         }
 
@@ -110,9 +117,12 @@ impl TidyDocs {
 
         if first_line.starts_with("//!") {
             if first_line.contains("FIXME") {
-                self.contains_fixme.push(path.to_path_buf())
+                self.contains_fixme.push(path.to_path_buf());
             }
         } else {
+            if text.contains("// Feature:") || text.contains("// Assist:") {
+                return;
+            }
             self.missing_docs.push(path.display().to_string());
         }