41 files changed, 1505 insertions, 391 deletions

diff --git a/crates/ra_ide/src/call_hierarchy.rs b/crates/ra_ide/src/call_hierarchy.rs
index 85d1f0cb1..defd8176f 100644
--- a/crates/ra_ide/src/call_hierarchy.rs
+++ b/crates/ra_ide/src/call_hierarchy.rs
@@ -246,6 +246,35 @@ mod tests {
     }
 
     #[test]
+    fn test_call_hierarchy_in_tests_mod() {
+        check_hierarchy(
+            r#"
+            //- /lib.rs cfg:test
+            fn callee() {}
+            fn caller1() {
+                call<|>ee();
+            }
+
+            #[cfg(test)]
+            mod tests {
+                use super::*;
+
+                #[test]
+                fn test_caller() {
+                    callee();
+                }
+            }
+            "#,
+            "callee FN_DEF FileId(1) 0..14 3..9",
+            &[
+                "caller1 FN_DEF FileId(1) 15..45 18..25 : [34..40]",
+                "test_caller FN_DEF FileId(1) 93..147 108..119 : [132..138]",
+            ],
+            &[],
+        );
+    }
+
+    #[test]
     fn test_call_hierarchy_in_different_files() {
         check_hierarchy(
             r#"
diff --git a/crates/ra_ide/src/completion.rs b/crates/ra_ide/src/completion.rs
index 191300704..a721e23c6 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.
@@ -82,3 +125,81 @@ pub(crate) fn completions(
 
     Some(acc)
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::completion::completion_config::CompletionConfig;
+    use crate::mock_analysis::analysis_and_position;
+
+    struct DetailAndDocumentation<'a> {
+        detail: &'a str,
+        documentation: &'a str,
+    }
+
+    fn check_detail_and_documentation(fixture: &str, expected: DetailAndDocumentation) {
+        let (analysis, position) = analysis_and_position(fixture);
+        let config = CompletionConfig::default();
+        let completions = analysis.completions(&config, position).unwrap().unwrap();
+        for item in completions {
+            if item.detail() == Some(expected.detail) {
+                let opt = item.documentation();
+                let doc = opt.as_ref().map(|it| it.as_str());
+                assert_eq!(doc, Some(expected.documentation));
+                return;
+            }
+        }
+        panic!("completion detail not found: {}", expected.detail)
+    }
+
+    #[test]
+    fn test_completion_detail_from_macro_generated_struct_fn_doc_attr() {
+        check_detail_and_documentation(
+            r#"
+            //- /lib.rs
+            macro_rules! bar {
+                () => {
+                    struct Bar;
+                    impl Bar {
+                        #[doc = "Do the foo"]
+                        fn foo(&self) {}
+                    }
+                }
+            }
+
+            bar!();
+
+            fn foo() {
+                let bar = Bar;
+                bar.fo<|>;
+            }
+            "#,
+            DetailAndDocumentation { detail: "fn foo(&self)", documentation: "Do the foo" },
+        );
+    }
+
+    #[test]
+    fn test_completion_detail_from_macro_generated_struct_fn_doc_comment() {
+        check_detail_and_documentation(
+            r#"
+            //- /lib.rs
+            macro_rules! bar {
+                () => {
+                    struct Bar;
+                    impl Bar {
+                        /// Do the foo
+                        fn foo(&self) {}
+                    }
+                }
+            }
+
+            bar!();
+
+            fn foo() {
+                let bar = Bar;
+                bar.fo<|>;
+            }
+            "#,
+            DetailAndDocumentation { detail: "fn foo(&self)", documentation: " Do the foo" },
+        );
+    }
+}
diff --git a/crates/ra_ide/src/completion/complete_attribute.rs b/crates/ra_ide/src/completion/complete_attribute.rs
index f17266221..fb3f0b743 100644
--- a/crates/ra_ide/src/completion/complete_attribute.rs
+++ b/crates/ra_ide/src/completion/complete_attribute.rs
@@ -112,7 +112,7 @@ const ATTRIBUTES: &[AttrCompletion] = &[
     AttrCompletion { label: "repr", snippet: Some("repr(${0:C})"), should_be_inner: false },
     AttrCompletion {
         label: "should_panic",
-        snippet: Some(r#"expected = "${0:reason}""#),
+        snippet: Some(r#"should_panic(expected = "${0:reason}")"#),
         should_be_inner: false,
     },
     AttrCompletion {
@@ -571,7 +571,7 @@ mod tests {
                 label: "should_panic",
                 source_range: 19..19,
                 delete: 19..19,
-                insert: "expected = \"${0:reason}\"",
+                insert: "should_panic(expected = \"${0:reason}\")",
                 kind: Attribute,
             },
             CompletionItem {
@@ -810,7 +810,7 @@ mod tests {
                 label: "should_panic",
                 source_range: 20..20,
                 delete: 20..20,
-                insert: "expected = \"${0:reason}\"",
+                insert: "should_panic(expected = \"${0:reason}\")",
                 kind: Attribute,
             },
             CompletionItem {
diff --git a/crates/ra_ide/src/completion/complete_postfix.rs b/crates/ra_ide/src/completion/complete_postfix.rs
index f2a52a407..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 {
@@ -184,6 +184,16 @@ pub(super) fn complete_postfix(acc: &mut Completions, ctx: &CompletionContext) {
         &format!("dbg!({})", receiver_text),
     )
     .add_to(acc);
+
+    postfix_snippet(
+        ctx,
+        cap,
+        &dot_receiver,
+        "call",
+        "function(expr)",
+        &format!("${{1}}({})", receiver_text),
+    )
+    .add_to(acc);
 }
 
 fn get_receiver_text(receiver: &ast::Expr, receiver_is_ambiguous_float_literal: bool) -> String {
@@ -256,6 +266,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 89..89,
+                delete: 85..89,
+                insert: "${1}(bar)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 89..89,
                 delete: 85..89,
@@ -335,6 +352,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 210..210,
+                delete: 206..210,
+                insert: "${1}(bar)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 210..210,
                 delete: 206..210,
@@ -414,6 +438,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 211..211,
+                delete: 207..211,
+                insert: "${1}(bar)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 211..211,
                 delete: 207..211,
@@ -488,6 +519,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 91..91,
+                delete: 87..91,
+                insert: "${1}(bar)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 91..91,
                 delete: 87..91,
@@ -547,6 +585,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 52..52,
+                delete: 49..52,
+                insert: "${1}(42)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 52..52,
                 delete: 49..52,
@@ -608,6 +653,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 149..150,
+                delete: 145..150,
+                insert: "${1}(bar)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 149..150,
                 delete: 145..150,
@@ -667,6 +719,13 @@ mod tests {
                 detail: "Box::new(expr)",
             },
             CompletionItem {
+                label: "call",
+                source_range: 56..56,
+                delete: 49..56,
+                insert: "${1}(&&&&42)",
+                detail: "function(expr)",
+            },
+            CompletionItem {
                 label: "dbg",
                 source_range: 56..56,
                 delete: 49..56,
diff --git a/crates/ra_ide/src/completion/complete_trait_impl.rs b/crates/ra_ide/src/completion/complete_trait_impl.rs
index 039df03e0..21c9316e6 100644
--- a/crates/ra_ide/src/completion/complete_trait_impl.rs
+++ b/crates/ra_ide/src/completion/complete_trait_impl.rs
@@ -49,56 +49,53 @@ use crate::{
 pub(crate) fn complete_trait_impl(acc: &mut Completions, ctx: &CompletionContext) {
     if let Some((trigger, impl_def)) = completion_match(ctx) {
         match trigger.kind() {
-            SyntaxKind::NAME_REF => {
-                get_missing_assoc_items(&ctx.sema, &impl_def).iter().for_each(|item| match item {
+            SyntaxKind::NAME_REF => get_missing_assoc_items(&ctx.sema, &impl_def)
+                .into_iter()
+                .for_each(|item| match item {
                     hir::AssocItem::Function(fn_item) => {
-                        add_function_impl(&trigger, acc, ctx, &fn_item)
+                        add_function_impl(&trigger, acc, ctx, fn_item)
                     }
                     hir::AssocItem::TypeAlias(type_item) => {
-                        add_type_alias_impl(&trigger, acc, ctx, &type_item)
+                        add_type_alias_impl(&trigger, acc, ctx, type_item)
                     }
                     hir::AssocItem::Const(const_item) => {
-                        add_const_impl(&trigger, acc, ctx, &const_item)
+                        add_const_impl(&trigger, acc, ctx, const_item)
                     }
-                })
-            }
+                }),
 
             SyntaxKind::FN_DEF => {
-                for missing_fn in
-                    get_missing_assoc_items(&ctx.sema, &impl_def).iter().filter_map(|item| {
-                        match item {
-                            hir::AssocItem::Function(fn_item) => Some(fn_item),
-                            _ => None,
-                        }
+                for missing_fn in get_missing_assoc_items(&ctx.sema, &impl_def)
+                    .into_iter()
+                    .filter_map(|item| match item {
+                        hir::AssocItem::Function(fn_item) => Some(fn_item),
+                        _ => None,
                     })
                 {
-                    add_function_impl(&trigger, acc, ctx, &missing_fn);
+                    add_function_impl(&trigger, acc, ctx, missing_fn);
                 }
             }
 
             SyntaxKind::TYPE_ALIAS_DEF => {
-                for missing_fn in
-                    get_missing_assoc_items(&ctx.sema, &impl_def).iter().filter_map(|item| {
-                        match item {
-                            hir::AssocItem::TypeAlias(type_item) => Some(type_item),
-                            _ => None,
-                        }
+                for missing_fn in get_missing_assoc_items(&ctx.sema, &impl_def)
+                    .into_iter()
+                    .filter_map(|item| match item {
+                        hir::AssocItem::TypeAlias(type_item) => Some(type_item),
+                        _ => None,
                     })
                 {
-                    add_type_alias_impl(&trigger, acc, ctx, &missing_fn);
+                    add_type_alias_impl(&trigger, acc, ctx, missing_fn);
                 }
             }
 
             SyntaxKind::CONST_DEF => {
-                for missing_fn in
-                    get_missing_assoc_items(&ctx.sema, &impl_def).iter().filter_map(|item| {
-                        match item {
-                            hir::AssocItem::Const(const_item) => Some(const_item),
-                            _ => None,
-                        }
+                for missing_fn in get_missing_assoc_items(&ctx.sema, &impl_def)
+                    .into_iter()
+                    .filter_map(|item| match item {
+                        hir::AssocItem::Const(const_item) => Some(const_item),
+                        _ => None,
                     })
                 {
-                    add_const_impl(&trigger, acc, ctx, &missing_fn);
+                    add_const_impl(&trigger, acc, ctx, missing_fn);
                 }
             }
 
@@ -126,9 +123,9 @@ fn add_function_impl(
     fn_def_node: &SyntaxNode,
     acc: &mut Completions,
     ctx: &CompletionContext,
-    func: &hir::Function,
+    func: hir::Function,
 ) {
-    let signature = FunctionSignature::from_hir(ctx.db, *func);
+    let signature = FunctionSignature::from_hir(ctx.db, func);
 
     let fn_name = func.name(ctx.db).to_string();
 
@@ -167,7 +164,7 @@ fn add_type_alias_impl(
     type_def_node: &SyntaxNode,
     acc: &mut Completions,
     ctx: &CompletionContext,
-    type_alias: &hir::TypeAlias,
+    type_alias: hir::TypeAlias,
 ) {
     let alias_name = type_alias.name(ctx.db).to_string();
 
@@ -187,7 +184,7 @@ fn add_const_impl(
     const_def_node: &SyntaxNode,
     acc: &mut Completions,
     ctx: &CompletionContext,
-    const_: &hir::Const,
+    const_: hir::Const,
 ) {
     let const_name = const_.name(ctx.db).map(|n| n.to_string());
 
diff --git a/crates/ra_ide/src/completion/complete_unqualified_path.rs b/crates/ra_ide/src/completion/complete_unqualified_path.rs
index db791660a..68032c37e 100644
--- a/crates/ra_ide/src/completion/complete_unqualified_path.rs
+++ b/crates/ra_ide/src/completion/complete_unqualified_path.rs
@@ -298,6 +298,42 @@ mod tests {
     }
 
     #[test]
+    fn completes_bindings_from_for_with_in_prefix() {
+        mark::check!(completes_bindings_from_for_with_in_prefix);
+        assert_debug_snapshot!(
+            do_reference_completion(
+                r"
+                fn test() {
+                    for index in &[1, 2, 3] {
+                        let t = in<|>
+                    }
+                }
+                "
+            ),
+            @r###"
+        [
+            CompletionItem {
+                label: "index",
+                source_range: 107..107,
+                delete: 107..107,
+                insert: "index",
+                kind: Binding,
+            },
+            CompletionItem {
+                label: "test()",
+                source_range: 107..107,
+                delete: 107..107,
+                insert: "test()$0",
+                kind: Function,
+                lookup: "test",
+                detail: "fn test()",
+            },
+        ]
+        "###
+        );
+    }
+
+    #[test]
     fn completes_generic_params() {
         assert_debug_snapshot!(
             do_reference_completion(
diff --git a/crates/ra_ide/src/completion/completion_context.rs b/crates/ra_ide/src/completion/completion_context.rs
index da336973c..c4646b727 100644
--- a/crates/ra_ide/src/completion/completion_context.rs
+++ b/crates/ra_ide/src/completion/completion_context.rs
@@ -12,6 +12,7 @@ use ra_syntax::{
 use ra_text_edit::Indel;
 
 use crate::{call_info::ActiveParameter, completion::CompletionConfig, FilePosition};
+use test_utils::mark;
 
 /// `CompletionContext` is created early during completion to figure out, where
 /// exactly is the cursor, syntax-wise.
@@ -169,7 +170,17 @@ impl<'a> CompletionContext<'a> {
         match self.token.kind() {
             // workaroud when completion is triggered by trigger characters.
             IDENT => self.original_token.text_range(),
-            _ => TextRange::empty(self.offset),
+            _ => {
+                // If we haven't characters between keyword and our cursor we take the keyword start range to edit
+                if self.token.kind().is_keyword()
+                    && self.offset == self.original_token.text_range().end()
+                {
+                    mark::hit!(completes_bindings_from_for_with_in_prefix);
+                    TextRange::empty(self.original_token.text_range().start())
+                } else {
+                    TextRange::empty(self.offset)
+                }
+            }
         }
     }
 
diff --git a/crates/ra_ide/src/completion/presentation.rs b/crates/ra_ide/src/completion/presentation.rs
index 440ffa31d..61565c84f 100644
--- a/crates/ra_ide/src/completion/presentation.rs
+++ b/crates/ra_ide/src/completion/presentation.rs
@@ -211,7 +211,7 @@ impl Completions {
             .parameter_names
             .iter()
             .skip(if function_signature.has_self_param { 1 } else { 0 })
-            .cloned()
+            .map(|name| name.trim_start_matches('_').into())
             .collect();
 
         builder = builder.add_call_parens(ctx, name, Params::Named(params));
@@ -672,6 +672,37 @@ mod tests {
         assert_debug_snapshot!(
             do_reference_completion(
                 r"
+                fn with_ignored_args(_foo: i32, ___bar: bool, ho_ge_: String) {}
+                fn main() { with_<|> }
+                "
+            ),
+            @r###"
+        [
+            CompletionItem {
+                label: "main()",
+                source_range: 110..115,
+                delete: 110..115,
+                insert: "main()$0",
+                kind: Function,
+                lookup: "main",
+                detail: "fn main()",
+            },
+            CompletionItem {
+                label: "with_ignored_args(…)",
+                source_range: 110..115,
+                delete: 110..115,
+                insert: "with_ignored_args(${1:foo}, ${2:bar}, ${3:ho_ge_})$0",
+                kind: Function,
+                lookup: "with_ignored_args",
+                detail: "fn with_ignored_args(_foo: i32, ___bar: bool, ho_ge_: String)",
+                trigger_call_info: true,
+            },
+        ]
+        "###
+        );
+        assert_debug_snapshot!(
+            do_reference_completion(
+                r"
                 struct S {}
                 impl S {
                     fn foo(&self) {}
@@ -695,6 +726,33 @@ mod tests {
         ]
         "###
         );
+        assert_debug_snapshot!(
+            do_reference_completion(
+                r"
+                struct S {}
+                impl S {
+                    fn foo_ignored_args(&self, _a: bool, b: i32) {}
+                }
+                fn bar(s: &S) {
+                    s.f<|>
+                }
+                "
+            ),
+            @r###"
+        [
+            CompletionItem {
+                label: "foo_ignored_args(…)",
+                source_range: 194..195,
+                delete: 194..195,
+                insert: "foo_ignored_args(${1:a}, ${2:b})$0",
+                kind: Method,
+                lookup: "foo_ignored_args",
+                detail: "fn foo_ignored_args(&self, _a: bool, b: i32)",
+                trigger_call_info: true,
+            },
+        ]
+        "###
+        );
     }
 
     #[test]
diff --git a/crates/ra_ide/src/diagnostics.rs b/crates/ra_ide/src/diagnostics.rs
index 3d83c0f71..15dc50cf1 100644
--- a/crates/ra_ide/src/diagnostics.rs
+++ b/crates/ra_ide/src/diagnostics.rs
@@ -664,7 +664,7 @@ mod tests {
         assert_debug_snapshot!(diagnostics, @r###"
         [
             Diagnostic {
-                message: "Missing structure fields:\n- b",
+                message: "Missing structure fields:\n- b\n",
                 range: 224..233,
                 severity: Error,
                 fix: Some(
diff --git a/crates/ra_ide/src/display.rs b/crates/ra_ide/src/display.rs
index 722092de9..827c094e7 100644
--- a/crates/ra_ide/src/display.rs
+++ b/crates/ra_ide/src/display.rs
@@ -79,16 +79,17 @@ pub(crate) fn rust_code_markup_with_doc(
     doc: Option<&str>,
     mod_path: Option<&str>,
 ) -> String {
-    let mut buf = "```rust\n".to_owned();
+    let mut buf = String::new();
 
     if let Some(mod_path) = mod_path {
         if !mod_path.is_empty() {
-            format_to!(buf, "{}\n", mod_path);
+            format_to!(buf, "```rust\n{}\n```\n\n", mod_path);
         }
     }
-    format_to!(buf, "{}\n```", code);
+    format_to!(buf, "```rust\n{}\n```", code);
 
     if let Some(doc) = doc {
+        format_to!(buf, "\n___");
         format_to!(buf, "\n\n{}", doc);
     }
 
diff --git a/crates/ra_ide/src/display/function_signature.rs b/crates/ra_ide/src/display/function_signature.rs
index 9572debd8..ca8a6a650 100644
--- a/crates/ra_ide/src/display/function_signature.rs
+++ b/crates/ra_ide/src/display/function_signature.rs
@@ -10,7 +10,7 @@ use std::{
 use hir::{Docs, Documentation, HasSource, HirDisplay};
 use ra_ide_db::RootDatabase;
 use ra_syntax::ast::{self, AstNode, NameOwner, VisibilityOwner};
-use stdx::SepBy;
+use stdx::{split1, SepBy};
 
 use crate::display::{generic_parameters, where_predicates};
 
@@ -207,7 +207,16 @@ impl From<&'_ ast::FnDef> for FunctionSignature {
                     res.push(raw_param);
                 }
 
-                res.extend(param_list.params().map(|param| param.syntax().text().to_string()));
+                // macro-generated functions are missing whitespace
+                fn fmt_param(param: ast::Param) -> String {
+                    let text = param.syntax().text().to_string();
+                    match split1(&text, ':') {
+                        Some((left, right)) => format!("{}: {}", left.trim(), right.trim()),
+                        _ => text,
+                    }
+                }
+
+                res.extend(param_list.params().map(fmt_param));
                 res_types.extend(param_list.params().map(|param| {
                     let param_text = param.syntax().text().to_string();
                     match param_text.split(':').nth(1).and_then(|it| it.get(1..)) {
diff --git a/crates/ra_ide/src/display/navigation_target.rs b/crates/ra_ide/src/display/navigation_target.rs
index 5da28edd2..c7bb1e69f 100644
--- a/crates/ra_ide/src/display/navigation_target.rs
+++ b/crates/ra_ide/src/display/navigation_target.rs
@@ -92,15 +92,16 @@ impl NavigationTarget {
         let name = module.name(db).map(|it| it.to_string().into()).unwrap_or_default();
         if let Some(src) = module.declaration_source(db) {
             let frange = original_range(db, src.as_ref().map(|it| it.syntax()));
-            return NavigationTarget::from_syntax(
+            let mut res = NavigationTarget::from_syntax(
                 frange.file_id,
                 name,
                 None,
                 frange.range,
                 src.value.syntax().kind(),
-                src.value.doc_comment_text(),
-                src.value.short_label(),
             );
+            res.docs = src.value.doc_comment_text();
+            res.description = src.value.short_label();
+            return res;
         }
         module.to_nav(db)
     }
@@ -130,11 +131,9 @@ impl NavigationTarget {
     }
 
     /// Allows `NavigationTarget` to be created from a `NameOwner`
-    fn from_named(
+    pub(crate) fn from_named(
         db: &RootDatabase,
         node: InFile<&dyn ast::NameOwner>,
-        docs: Option<String>,
-        description: Option<String>,
     ) -> NavigationTarget {
         //FIXME: use `_` instead of empty string
         let name = node.value.name().map(|it| it.text().clone()).unwrap_or_default();
@@ -148,8 +147,6 @@ impl NavigationTarget {
             focus_range,
             frange.range,
             node.value.syntax().kind(),
-            docs,
-            description,
         )
     }
 
@@ -159,8 +156,6 @@ impl NavigationTarget {
         focus_range: Option<TextRange>,
         full_range: TextRange,
         kind: SyntaxKind,
-        docs: Option<String>,
-        description: Option<String>,
     ) -> NavigationTarget {
         NavigationTarget {
             file_id,
@@ -169,8 +164,8 @@ impl NavigationTarget {
             full_range,
             focus_range,
             container_name: None,
-            description,
-            docs,
+            description: None,
+            docs: None,
         }
     }
 }
@@ -238,12 +233,11 @@ where
 {
     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget {
         let src = self.source(db);
-        NavigationTarget::from_named(
-            db,
-            src.as_ref().map(|it| it as &dyn ast::NameOwner),
-            src.value.doc_comment_text(),
-            src.value.short_label(),
-        )
+        let mut res =
+            NavigationTarget::from_named(db, src.as_ref().map(|it| it as &dyn ast::NameOwner));
+        res.docs = src.value.doc_comment_text();
+        res.description = src.value.short_label();
+        res
     }
 }
 
@@ -258,15 +252,7 @@ impl ToNav for hir::Module {
             }
         };
         let frange = original_range(db, src.with_value(syntax));
-        NavigationTarget::from_syntax(
-            frange.file_id,
-            name,
-            focus,
-            frange.range,
-            syntax.kind(),
-            None,
-            None,
-        )
+        NavigationTarget::from_syntax(frange.file_id, name, focus, frange.range, syntax.kind())
     }
 }
 
@@ -285,8 +271,6 @@ impl ToNav for hir::ImplDef {
             None,
             frange.range,
             src.value.syntax().kind(),
-            None,
-            None,
         )
     }
 }
@@ -296,12 +280,12 @@ impl ToNav for hir::Field {
         let src = self.source(db);
 
         match &src.value {
-            FieldSource::Named(it) => NavigationTarget::from_named(
-                db,
-                src.with_value(it),
-                it.doc_comment_text(),
-                it.short_label(),
-            ),
+            FieldSource::Named(it) => {
+                let mut res = NavigationTarget::from_named(db, src.with_value(it));
+                res.docs = it.doc_comment_text();
+                res.description = it.short_label();
+                res
+            }
             FieldSource::Pos(it) => {
                 let frange = original_range(db, src.with_value(it.syntax()));
                 NavigationTarget::from_syntax(
@@ -310,8 +294,6 @@ impl ToNav for hir::Field {
                     None,
                     frange.range,
                     it.syntax().kind(),
-                    None,
-                    None,
                 )
             }
         }
@@ -322,12 +304,10 @@ impl ToNav for hir::MacroDef {
     fn to_nav(&self, db: &RootDatabase) -> NavigationTarget {
         let src = self.source(db);
         log::debug!("nav target {:#?}", src.value.syntax());
-        NavigationTarget::from_named(
-            db,
-            src.as_ref().map(|it| it as &dyn ast::NameOwner),
-            src.value.doc_comment_text(),
-            None,
-        )
+        let mut res =
+            NavigationTarget::from_named(db, src.as_ref().map(|it| it as &dyn ast::NameOwner));
+        res.docs = src.value.doc_comment_text();
+        res
     }
 }
 
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 befa977c7..9636cd0d6 100644
--- a/crates/ra_ide/src/hover.rs
+++ b/crates/ra_ide/src/hover.rs
@@ -1,28 +1,21 @@
-//! 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,
+    Adt, AsAssocItem, AssocItemContainer, Documentation, FieldSource, HasSource, HirDisplay,
+    ModuleDef, ModuleSource, Semantics,
 };
+use itertools::Itertools;
 use ra_db::SourceDatabase;
 use ra_ide_db::{
     defs::{classify_name, classify_name_ref, Definition},
     RootDatabase,
 };
-use ra_syntax::{
-    ast::{self, DocCommentsOwner},
-    match_ast, AstNode,
-    SyntaxKind::*,
-    SyntaxToken, TokenAtOffset,
-};
+use ra_syntax::{ast, match_ast, AstNode, SyntaxKind::*, SyntaxToken, TokenAtOffset};
 
 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 +55,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>,
@@ -114,13 +164,15 @@ fn hover_text_from_name_kind(db: &RootDatabase, def: Definition) -> Option<Strin
     return match def {
         Definition::Macro(it) => {
             let src = it.source(db);
-            hover_text(src.value.doc_comment_text(), Some(macro_label(&src.value)), mod_path)
+            let docs = Documentation::from_ast(&src.value).map(Into::into);
+            hover_text(docs, Some(macro_label(&src.value)), mod_path)
         }
         Definition::Field(it) => {
             let src = it.source(db);
             match src.value {
                 FieldSource::Named(it) => {
-                    hover_text(it.doc_comment_text(), it.short_label(), mod_path)
+                    let docs = Documentation::from_ast(&it).map(Into::into);
+                    hover_text(docs, it.short_label(), mod_path)
                 }
                 _ => None,
             }
@@ -128,7 +180,8 @@ fn hover_text_from_name_kind(db: &RootDatabase, def: Definition) -> Option<Strin
         Definition::ModuleDef(it) => match it {
             ModuleDef::Module(it) => match it.definition_source(db).value {
                 ModuleSource::Module(it) => {
-                    hover_text(it.doc_comment_text(), it.short_label(), mod_path)
+                    let docs = Documentation::from_ast(&it).map(Into::into);
+                    hover_text(docs, it.short_label(), mod_path)
                 }
                 _ => None,
             },
@@ -153,66 +206,14 @@ fn hover_text_from_name_kind(db: &RootDatabase, def: Definition) -> Option<Strin
     fn from_def_source<A, D>(db: &RootDatabase, def: D, mod_path: Option<String>) -> Option<String>
     where
         D: HasSource<Ast = A>,
-        A: ast::DocCommentsOwner + ast::NameOwner + ShortLabel,
+        A: ast::DocCommentsOwner + ast::NameOwner + ShortLabel + ast::AttrsOwner,
     {
         let src = def.source(db);
-        hover_text(src.value.doc_comment_text(), src.value.short_label(), mod_path)
+        let docs = Documentation::from_ast(&src.value).map(Into::into);
+        hover_text(docs, src.value.short_label(), mod_path)
     }
 }
 
-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 {
@@ -405,7 +406,7 @@ mod tests {
                 };
             }
         "#,
-            &["Foo\nfield_a: u32"],
+            &["Foo\n```\n\n```rust\nfield_a: u32"],
         );
 
         // Hovering over the field in the definition
@@ -422,7 +423,7 @@ mod tests {
                 };
             }
         "#,
-            &["Foo\nfield_a: u32"],
+            &["Foo\n```\n\n```rust\nfield_a: u32"],
         );
     }
 
@@ -475,7 +476,7 @@ fn main() {
             ",
         );
         let hover = analysis.hover(position).unwrap().unwrap();
-        assert_eq!(trim_markup_opt(hover.info.first()), Some("Option\nSome"));
+        assert_eq!(trim_markup_opt(hover.info.first()), Some("Option\n```\n\n```rust\nSome"));
 
         let (analysis, position) = single_file_with_position(
             "
@@ -503,8 +504,12 @@ fn main() {
         "#,
             &["
 Option
+```
+
+```rust
 None
 ```
+___
 
 The None variant
             "
@@ -524,8 +529,12 @@ The None variant
         "#,
             &["
 Option
+```
+
+```rust
 Some
 ```
+___
 
 The Some variant
             "
@@ -606,7 +615,10 @@ fn func(foo: i32) { if true { <|>foo; }; }
             ",
         );
         let hover = analysis.hover(position).unwrap().unwrap();
-        assert_eq!(trim_markup_opt(hover.info.first()), Some("wrapper::Thing\nfn new() -> Thing"));
+        assert_eq!(
+            trim_markup_opt(hover.info.first()),
+            Some("wrapper::Thing\n```\n\n```rust\nfn new() -> Thing")
+        );
     }
 
     #[test]
@@ -882,7 +894,7 @@ fn func(foo: i32) { if true { <|>foo; }; }
                 fo<|>o();
             }
             ",
-            &["fn foo()\n```\n\n<- `\u{3000}` here"],
+            &["fn foo()\n```\n___\n\n<- `\u{3000}` here"],
         );
     }
 
@@ -938,4 +950,106 @@ fn func(foo: i32) { if true { <|>foo; }; }
             &["mod my"],
         );
     }
+
+    #[test]
+    fn test_hover_struct_doc_comment() {
+        check_hover_result(
+            r#"
+            //- /lib.rs
+            /// bar docs
+            struct Bar;
+
+            fn foo() {
+                let bar = Ba<|>r;
+            }
+            "#,
+            &["struct Bar\n```\n___\n\nbar docs"],
+        );
+    }
+
+    #[test]
+    fn test_hover_struct_doc_attr() {
+        check_hover_result(
+            r#"
+            //- /lib.rs
+            #[doc = "bar docs"]
+            struct Bar;
+
+            fn foo() {
+                let bar = Ba<|>r;
+            }
+            "#,
+            &["struct Bar\n```\n___\n\nbar docs"],
+        );
+    }
+
+    #[test]
+    fn test_hover_struct_doc_attr_multiple_and_mixed() {
+        check_hover_result(
+            r#"
+            //- /lib.rs
+            /// bar docs 0
+            #[doc = "bar docs 1"]
+            #[doc = "bar docs 2"]
+            struct Bar;
+
+            fn foo() {
+                let bar = Ba<|>r;
+            }
+            "#,
+            &["struct Bar\n```\n___\n\nbar docs 0\n\nbar docs 1\n\nbar docs 2"],
+        );
+    }
+
+    #[test]
+    fn test_hover_macro_generated_struct_fn_doc_comment() {
+        check_hover_result(
+            r#"
+            //- /lib.rs
+            macro_rules! bar {
+                () => {
+                    struct Bar;
+                    impl Bar {
+                        /// Do the foo
+                        fn foo(&self) {}
+                    }
+                }
+            }
+
+            bar!();
+
+            fn foo() {
+                let bar = Bar;
+                bar.fo<|>o();
+            }
+            "#,
+            &["Bar\n```\n\n```rust\nfn foo(&self)\n```\n___\n\n Do the foo"],
+        );
+    }
+
+    #[test]
+    fn test_hover_macro_generated_struct_fn_doc_attr() {
+        check_hover_result(
+            r#"
+            //- /lib.rs
+            macro_rules! bar {
+                () => {
+                    struct Bar;
+                    impl Bar {
+                        #[doc = "Do the foo"]
+                        fn foo(&self) {}
+                    }
+                }
+            }
+
+            bar!();
+
+            fn foo() {
+                let bar = Bar;
+                bar.fo<|>o();
+            }
+            "#,
+            &["Bar\n```\n\n```rust\nfn foo(&self)\n```\n___\n\nDo the foo"],
+        );
+    }
 }
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 5ac002d82..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;
@@ -309,7 +309,8 @@ impl Analysis {
 
     /// Returns an edit which should be applied when opening a new line, fixing
     /// up minor stuff like continuing the comment.
-    pub fn on_enter(&self, position: FilePosition) -> Cancelable<Option<SourceChange>> {
+    /// The edit will be a snippet (with `$0`).
+    pub fn on_enter(&self, position: FilePosition) -> Cancelable<Option<TextEdit>> {
         self.with_db(|db| typing::on_enter(&db, position))
     }
 
@@ -372,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/mock_analysis.rs b/crates/ra_ide/src/mock_analysis.rs
index 2c13f206a..ad78d2d93 100644
--- a/crates/ra_ide/src/mock_analysis.rs
+++ b/crates/ra_ide/src/mock_analysis.rs
@@ -1,21 +1,81 @@
 //! FIXME: write short doc here
 
+use std::str::FromStr;
 use std::sync::Arc;
 
 use ra_cfg::CfgOptions;
 use ra_db::{CrateName, Env, RelativePathBuf};
-use test_utils::{extract_offset, extract_range, parse_fixture, CURSOR_MARKER};
+use test_utils::{extract_offset, extract_range, parse_fixture, FixtureEntry, CURSOR_MARKER};
 
 use crate::{
-    Analysis, AnalysisChange, AnalysisHost, CrateGraph, Edition::Edition2018, FileId, FilePosition,
-    FileRange, SourceRootId,
+    Analysis, AnalysisChange, AnalysisHost, CrateGraph, Edition, FileId, FilePosition, FileRange,
+    SourceRootId,
 };
 
+#[derive(Debug)]
+enum MockFileData {
+    Plain { path: String, content: String },
+    Fixture(FixtureEntry),
+}
+
+impl MockFileData {
+    fn new(path: String, content: String) -> Self {
+        // `Self::Plain` causes a false warning: 'variant is never constructed: `Plain` '
+        // see https://github.com/rust-lang/rust/issues/69018
+        MockFileData::Plain { path, content }
+    }
+
+    fn path(&self) -> &str {
+        match self {
+            MockFileData::Plain { path, .. } => path.as_str(),
+            MockFileData::Fixture(f) => f.meta.path().as_str(),
+        }
+    }
+
+    fn content(&self) -> &str {
+        match self {
+            MockFileData::Plain { content, .. } => content,
+            MockFileData::Fixture(f) => f.text.as_str(),
+        }
+    }
+
+    fn cfg_options(&self) -> CfgOptions {
+        match self {
+            MockFileData::Fixture(f) => {
+                f.meta.cfg_options().map_or_else(Default::default, |o| o.clone())
+            }
+            _ => CfgOptions::default(),
+        }
+    }
+
+    fn edition(&self) -> Edition {
+        match self {
+            MockFileData::Fixture(f) => {
+                f.meta.edition().map_or(Edition::Edition2018, |v| Edition::from_str(v).unwrap())
+            }
+            _ => Edition::Edition2018,
+        }
+    }
+
+    fn env(&self) -> Env {
+        match self {
+            MockFileData::Fixture(f) => Env::from(f.meta.env()),
+            _ => Env::default(),
+        }
+    }
+}
+
+impl From<FixtureEntry> for MockFileData {
+    fn from(fixture: FixtureEntry) -> Self {
+        Self::Fixture(fixture)
+    }
+}
+
 /// Mock analysis is used in test to bootstrap an AnalysisHost/Analysis
 /// from a set of in-memory files.
 #[derive(Debug, Default)]
 pub struct MockAnalysis {
-    files: Vec<(String, String)>,
+    files: Vec<MockFileData>,
 }
 
 impl MockAnalysis {
@@ -35,7 +95,7 @@ impl MockAnalysis {
     pub fn with_files(fixture: &str) -> MockAnalysis {
         let mut res = MockAnalysis::new();
         for entry in parse_fixture(fixture) {
-            res.add_file(&entry.meta, &entry.text);
+            res.add_file_fixture(entry);
         }
         res
     }
@@ -48,30 +108,44 @@ impl MockAnalysis {
         for entry in parse_fixture(fixture) {
             if entry.text.contains(CURSOR_MARKER) {
                 assert!(position.is_none(), "only one marker (<|>) per fixture is allowed");
-                position = Some(res.add_file_with_position(&entry.meta, &entry.text));
+                position = Some(res.add_file_fixture_with_position(entry));
             } else {
-                res.add_file(&entry.meta, &entry.text);
+                res.add_file_fixture(entry);
             }
         }
         let position = position.expect("expected a marker (<|>)");
         (res, position)
     }
 
+    pub fn add_file_fixture(&mut self, fixture: FixtureEntry) -> FileId {
+        let file_id = self.next_id();
+        self.files.push(MockFileData::from(fixture));
+        file_id
+    }
+
+    pub fn add_file_fixture_with_position(&mut self, mut fixture: FixtureEntry) -> FilePosition {
+        let (offset, text) = extract_offset(&fixture.text);
+        fixture.text = text;
+        let file_id = self.next_id();
+        self.files.push(MockFileData::from(fixture));
+        FilePosition { file_id, offset }
+    }
+
     pub fn add_file(&mut self, path: &str, text: &str) -> FileId {
-        let file_id = FileId((self.files.len() + 1) as u32);
-        self.files.push((path.to_string(), text.to_string()));
+        let file_id = self.next_id();
+        self.files.push(MockFileData::new(path.to_string(), text.to_string()));
         file_id
     }
     pub fn add_file_with_position(&mut self, path: &str, text: &str) -> FilePosition {
         let (offset, text) = extract_offset(text);
-        let file_id = FileId((self.files.len() + 1) as u32);
-        self.files.push((path.to_string(), text));
+        let file_id = self.next_id();
+        self.files.push(MockFileData::new(path.to_string(), text));
         FilePosition { file_id, offset }
     }
     pub fn add_file_with_range(&mut self, path: &str, text: &str) -> FileRange {
         let (range, text) = extract_range(text);
-        let file_id = FileId((self.files.len() + 1) as u32);
-        self.files.push((path.to_string(), text));
+        let file_id = self.next_id();
+        self.files.push(MockFileData::new(path.to_string(), text));
         FileRange { file_id, range }
     }
     pub fn id_of(&self, path: &str) -> FileId {
@@ -79,7 +153,7 @@ impl MockAnalysis {
             .files
             .iter()
             .enumerate()
-            .find(|(_, (p, _text))| path == p)
+            .find(|(_, data)| path == data.path())
             .expect("no file in this mock");
         FileId(idx as u32 + 1)
     }
@@ -90,18 +164,21 @@ impl MockAnalysis {
         change.add_root(source_root, true);
         let mut crate_graph = CrateGraph::default();
         let mut root_crate = None;
-        for (i, (path, contents)) in self.files.into_iter().enumerate() {
+        for (i, data) in self.files.into_iter().enumerate() {
+            let path = data.path();
             assert!(path.starts_with('/'));
             let path = RelativePathBuf::from_path(&path[1..]).unwrap();
+            let cfg_options = data.cfg_options();
             let file_id = FileId(i as u32 + 1);
-            let cfg_options = CfgOptions::default();
+            let edition = data.edition();
+            let env = data.env();
             if path == "/lib.rs" || path == "/main.rs" {
                 root_crate = Some(crate_graph.add_crate_root(
                     file_id,
-                    Edition2018,
+                    edition,
                     None,
                     cfg_options,
-                    Env::default(),
+                    env,
                     Default::default(),
                     Default::default(),
                 ));
@@ -109,10 +186,10 @@ impl MockAnalysis {
                 let crate_name = path.parent().unwrap().file_name().unwrap();
                 let other_crate = crate_graph.add_crate_root(
                     file_id,
-                    Edition2018,
+                    edition,
                     Some(CrateName::new(crate_name).unwrap()),
                     cfg_options,
-                    Env::default(),
+                    env,
                     Default::default(),
                     Default::default(),
                 );
@@ -122,7 +199,7 @@ impl MockAnalysis {
                         .unwrap();
                 }
             }
-            change.add_file(source_root, file_id, path, Arc::new(contents));
+            change.add_file(source_root, file_id, path, Arc::new(data.content().to_owned()));
         }
         change.set_crate_graph(crate_graph);
         host.apply_change(change);
@@ -131,6 +208,10 @@ impl MockAnalysis {
     pub fn analysis(self) -> Analysis {
         self.analysis_host().analysis()
     }
+
+    fn next_id(&self) -> FileId {
+        FileId((self.files.len() + 1) as u32)
+    }
 }
 
 /// Creates analysis from a multi-file fixture, returns positions marked with <|>.
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 131b8f307..f32ce0d22 100644
--- a/crates/ra_ide/src/runnables.rs
+++ b/crates/ra_ide/src/runnables.rs
@@ -1,21 +1,21 @@
-//! FIXME: write short doc here
+use std::fmt;
 
-use hir::{AsAssocItem, Semantics};
+use hir::{AsAssocItem, Attrs, HirFileId, InFile, Semantics};
 use itertools::Itertools;
+use ra_cfg::CfgExpr;
 use ra_ide_db::RootDatabase;
 use ra_syntax::{
-    ast::{self, AstNode, AttrsOwner, ModuleItemOwner, NameOwner},
-    match_ast, SyntaxNode, TextRange,
+    ast::{self, AstNode, AttrsOwner, DocCommentsOwner, ModuleItemOwner, NameOwner},
+    match_ast, SyntaxNode,
 };
 
-use crate::FileId;
-use ast::DocCommentsOwner;
-use std::fmt::Display;
+use crate::{display::ToNav, FileId, NavigationTarget};
 
 #[derive(Debug)]
 pub struct Runnable {
-    pub range: TextRange,
+    pub nav: NavigationTarget,
     pub kind: RunnableKind,
+    pub cfg_exprs: Vec<CfgExpr>,
 }
 
 #[derive(Debug)]
@@ -24,8 +24,8 @@ pub enum TestId {
     Path(String),
 }
 
-impl Display for TestId {
-    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+impl fmt::Display for TestId {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match self {
             TestId::Name(name) => write!(f, "{}", name),
             TestId::Path(path) => write!(f, "{}", path),
@@ -42,32 +42,47 @@ 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);
-    source_file.syntax().descendants().filter_map(|i| runnable(&sema, i)).collect()
+    source_file.syntax().descendants().filter_map(|i| runnable(&sema, i, file_id)).collect()
 }
 
-fn runnable(sema: &Semantics<RootDatabase>, item: SyntaxNode) -> Option<Runnable> {
+fn runnable(sema: &Semantics<RootDatabase>, item: SyntaxNode, file_id: FileId) -> Option<Runnable> {
     match_ast! {
         match item {
-            ast::FnDef(it) => runnable_fn(sema, it),
-            ast::Module(it) => runnable_mod(sema, it),
+            ast::FnDef(it) => runnable_fn(sema, it, file_id),
+            ast::Module(it) => runnable_mod(sema, it, file_id),
             _ => None,
         }
     }
 }
 
-fn runnable_fn(sema: &Semantics<RootDatabase>, fn_def: ast::FnDef) -> Option<Runnable> {
+fn runnable_fn(
+    sema: &Semantics<RootDatabase>,
+    fn_def: ast::FnDef,
+    file_id: FileId,
+) -> Option<Runnable> {
     let name_string = fn_def.name()?.text().to_string();
 
     let kind = if name_string == "main" {
         RunnableKind::Bin
     } else {
-        let test_id = if let Some(module) = sema.to_def(&fn_def).map(|def| def.module(sema.db)) {
-            let def = sema.to_def(&fn_def)?;
-            let impl_trait_name =
-                def.as_assoc_item(sema.db).and_then(|assoc_item| {
+        let test_id = match sema.to_def(&fn_def).map(|def| def.module(sema.db)) {
+            Some(module) => {
+                let def = sema.to_def(&fn_def)?;
+                let impl_trait_name = def.as_assoc_item(sema.db).and_then(|assoc_item| {
                     match assoc_item.container(sema.db) {
                         hir::AssocItemContainer::Trait(trait_item) => {
                             Some(trait_item.name(sema.db).to_string())
@@ -79,25 +94,25 @@ fn runnable_fn(sema: &Semantics<RootDatabase>, fn_def: ast::FnDef) -> Option<Run
                     }
                 });
 
-            let path_iter = module
-                .path_to_root(sema.db)
-                .into_iter()
-                .rev()
-                .filter_map(|it| it.name(sema.db))
-                .map(|name| name.to_string());
-
-            let path = if let Some(impl_trait_name) = impl_trait_name {
-                path_iter
-                    .chain(std::iter::once(impl_trait_name))
-                    .chain(std::iter::once(name_string))
-                    .join("::")
-            } else {
-                path_iter.chain(std::iter::once(name_string)).join("::")
-            };
-
-            TestId::Path(path)
-        } else {
-            TestId::Name(name_string)
+                let path_iter = module
+                    .path_to_root(sema.db)
+                    .into_iter()
+                    .rev()
+                    .filter_map(|it| it.name(sema.db))
+                    .map(|name| name.to_string());
+
+                let path = if let Some(impl_trait_name) = impl_trait_name {
+                    path_iter
+                        .chain(std::iter::once(impl_trait_name))
+                        .chain(std::iter::once(name_string))
+                        .join("::")
+                } else {
+                    path_iter.chain(std::iter::once(name_string)).join("::")
+                };
+
+                TestId::Path(path)
+            }
+            None => TestId::Name(name_string),
         };
 
         if has_test_related_attribute(&fn_def) {
@@ -111,7 +126,13 @@ fn runnable_fn(sema: &Semantics<RootDatabase>, fn_def: ast::FnDef) -> Option<Run
             return None;
         }
     };
-    Some(Runnable { range: fn_def.syntax().text_range(), kind })
+
+    let attrs = Attrs::from_attrs_owner(sema.db, InFile::new(HirFileId::from(file_id), &fn_def));
+    let cfg_exprs =
+        attrs.by_key("cfg").tt_values().map(|subtree| ra_cfg::parse_cfg(subtree)).collect();
+
+    let nav = NavigationTarget::from_named(sema.db, InFile::new(file_id.into(), &fn_def));
+    Some(Runnable { nav, kind, cfg_exprs })
 }
 
 #[derive(Debug)]
@@ -147,7 +168,11 @@ fn has_doc_test(fn_def: &ast::FnDef) -> bool {
     fn_def.doc_comment_text().map_or(false, |comment| comment.contains("```"))
 }
 
-fn runnable_mod(sema: &Semantics<RootDatabase>, module: ast::Module) -> Option<Runnable> {
+fn runnable_mod(
+    sema: &Semantics<RootDatabase>,
+    module: ast::Module,
+    file_id: FileId,
+) -> Option<Runnable> {
     let has_test_function = module
         .item_list()?
         .items()
@@ -159,12 +184,21 @@ fn runnable_mod(sema: &Semantics<RootDatabase>, module: ast::Module) -> Option<R
     if !has_test_function {
         return None;
     }
-    let range = module.syntax().text_range();
-    let module = sema.to_def(&module)?;
+    let module_def = sema.to_def(&module)?;
 
-    let path =
-        module.path_to_root(sema.db).into_iter().rev().filter_map(|it| it.name(sema.db)).join("::");
-    Some(Runnable { range, kind: RunnableKind::TestMod { path } })
+    let path = module_def
+        .path_to_root(sema.db)
+        .into_iter()
+        .rev()
+        .filter_map(|it| it.name(sema.db))
+        .join("::");
+
+    let attrs = Attrs::from_attrs_owner(sema.db, InFile::new(HirFileId::from(file_id), &module));
+    let cfg_exprs =
+        attrs.by_key("cfg").tt_values().map(|subtree| ra_cfg::parse_cfg(subtree)).collect();
+
+    let nav = module_def.to_nav(sema.db);
+    Some(Runnable { nav, kind: RunnableKind::TestMod { path }, cfg_exprs })
 }
 
 #[cfg(test)]
@@ -194,11 +228,38 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 1..21,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 1..21,
+                    name: "main",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        12..16,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Bin,
+                cfg_exprs: [],
             },
             Runnable {
-                range: 22..46,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 22..46,
+                    name: "test_foo",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        33..41,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Test {
                     test_id: Path(
                         "test_foo",
@@ -207,9 +268,23 @@ mod tests {
                         ignore: false,
                     },
                 },
+                cfg_exprs: [],
             },
             Runnable {
-                range: 47..81,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 47..81,
+                    name: "test_foo",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        68..76,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Test {
                     test_id: Path(
                         "test_foo",
@@ -218,6 +293,7 @@ mod tests {
                         ignore: true,
                     },
                 },
+                cfg_exprs: [],
             },
         ]
         "###
@@ -243,16 +319,44 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 1..21,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 1..21,
+                    name: "main",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        12..16,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Bin,
+                cfg_exprs: [],
             },
             Runnable {
-                range: 22..64,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 22..64,
+                    name: "foo",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        56..59,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: DocTest {
                     test_id: Path(
                         "foo",
                     ),
                 },
+                cfg_exprs: [],
             },
         ]
         "###
@@ -281,16 +385,44 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 1..21,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 1..21,
+                    name: "main",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        12..16,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Bin,
+                cfg_exprs: [],
             },
             Runnable {
-                range: 51..105,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 51..105,
+                    name: "foo",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        97..100,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: DocTest {
                     test_id: Path(
                         "Data::foo",
                     ),
                 },
+                cfg_exprs: [],
             },
         ]
         "###
@@ -314,13 +446,40 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 1..59,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 1..59,
+                    name: "test_mod",
+                    kind: MODULE,
+                    focus_range: Some(
+                        13..21,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: TestMod {
                     path: "test_mod",
                 },
+                cfg_exprs: [],
             },
             Runnable {
-                range: 28..57,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 28..57,
+                    name: "test_foo1",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        43..52,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Test {
                     test_id: Path(
                         "test_mod::test_foo1",
@@ -329,6 +488,7 @@ mod tests {
                         ignore: false,
                     },
                 },
+                cfg_exprs: [],
             },
         ]
         "###
@@ -354,13 +514,40 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 23..85,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 23..85,
+                    name: "test_mod",
+                    kind: MODULE,
+                    focus_range: Some(
+                        27..35,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: TestMod {
                     path: "foo::test_mod",
                 },
+                cfg_exprs: [],
             },
             Runnable {
-                range: 46..79,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 46..79,
+                    name: "test_foo1",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        65..74,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Test {
                     test_id: Path(
                         "foo::test_mod::test_foo1",
@@ -369,6 +556,7 @@ mod tests {
                         ignore: false,
                     },
                 },
+                cfg_exprs: [],
             },
         ]
         "###
@@ -396,13 +584,40 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 41..115,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 41..115,
+                    name: "test_mod",
+                    kind: MODULE,
+                    focus_range: Some(
+                        45..53,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: TestMod {
                     path: "foo::bar::test_mod",
                 },
+                cfg_exprs: [],
             },
             Runnable {
-                range: 68..105,
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 68..105,
+                    name: "test_foo1",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        91..100,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
                 kind: Test {
                     test_id: Path(
                         "foo::bar::test_mod::test_foo1",
@@ -411,6 +626,115 @@ mod tests {
                         ignore: false,
                     },
                 },
+                cfg_exprs: [],
+            },
+        ]
+        "###
+                );
+    }
+
+    #[test]
+    fn test_runnables_with_feature() {
+        let (analysis, pos) = analysis_and_position(
+            r#"
+        //- /lib.rs crate:foo cfg:feature=foo
+        <|> //empty
+        #[test]
+        #[cfg(feature = "foo")]
+        fn test_foo1() {}
+        "#,
+        );
+        let runnables = analysis.runnables(pos.file_id).unwrap();
+        assert_debug_snapshot!(&runnables,
+        @r###"
+        [
+            Runnable {
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 1..58,
+                    name: "test_foo1",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        44..53,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
+                kind: Test {
+                    test_id: Path(
+                        "test_foo1",
+                    ),
+                    attr: TestAttr {
+                        ignore: false,
+                    },
+                },
+                cfg_exprs: [
+                    KeyValue {
+                        key: "feature",
+                        value: "foo",
+                    },
+                ],
+            },
+        ]
+        "###
+                );
+    }
+
+    #[test]
+    fn test_runnables_with_features() {
+        let (analysis, pos) = analysis_and_position(
+            r#"
+        //- /lib.rs crate:foo cfg:feature=foo,feature=bar
+        <|> //empty
+        #[test]
+        #[cfg(all(feature = "foo", feature = "bar"))]
+        fn test_foo1() {}
+        "#,
+        );
+        let runnables = analysis.runnables(pos.file_id).unwrap();
+        assert_debug_snapshot!(&runnables,
+        @r###"
+        [
+            Runnable {
+                nav: NavigationTarget {
+                    file_id: FileId(
+                        1,
+                    ),
+                    full_range: 1..80,
+                    name: "test_foo1",
+                    kind: FN_DEF,
+                    focus_range: Some(
+                        66..75,
+                    ),
+                    container_name: None,
+                    description: None,
+                    docs: None,
+                },
+                kind: Test {
+                    test_id: Path(
+                        "test_foo1",
+                    ),
+                    attr: TestAttr {
+                        ignore: false,
+                    },
+                },
+                cfg_exprs: [
+                    All(
+                        [
+                            KeyValue {
+                                key: "feature",
+                                value: "foo",
+                            },
+                            KeyValue {
+                                key: "feature",
+                                value: "bar",
+                            },
+                        ],
+                    ),
+                ],
             },
         ]
         "###
diff --git a/crates/ra_ide/src/snapshots/highlight_injection.html b/crates/ra_ide/src/snapshots/highlight_injection.html
index ea026d7a0..fcdc98201 100644
--- a/crates/ra_ide/src/snapshots/highlight_injection.html
+++ b/crates/ra_ide/src/snapshots/highlight_injection.html
@@ -10,6 +10,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .string_literal     { color: #CC9393; }
 .field              { color: #94BFF3; }
 .function           { color: #93E0E3; }
+.operator.unsafe    { color: #E28C14; }
 .parameter          { color: #94BFF3; }
 .text               { color: #DCDCCC; }
 .type               { color: #7CB8BB; }
@@ -17,6 +18,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .type_param         { color: #DFAF8F; }
 .attribute          { color: #94BFF3; }
 .numeric_literal    { color: #BFEBBF; }
+.bool_literal       { color: #BFE6EB; }
 .macro              { color: #94BFF3; }
 .module             { color: #AFD8AF; }
 .variable           { color: #DCDCCC; }
diff --git a/crates/ra_ide/src/snapshots/highlight_strings.html b/crates/ra_ide/src/snapshots/highlight_strings.html
index 752b487e8..e97192b61 100644
--- a/crates/ra_ide/src/snapshots/highlight_strings.html
+++ b/crates/ra_ide/src/snapshots/highlight_strings.html
@@ -10,6 +10,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .string_literal     { color: #CC9393; }
 .field              { color: #94BFF3; }
 .function           { color: #93E0E3; }
+.operator.unsafe    { color: #E28C14; }
 .parameter          { color: #94BFF3; }
 .text               { color: #DCDCCC; }
 .type               { color: #7CB8BB; }
@@ -17,6 +18,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .type_param         { color: #DFAF8F; }
 .attribute          { color: #94BFF3; }
 .numeric_literal    { color: #BFEBBF; }
+.bool_literal       { color: #BFE6EB; }
 .macro              { color: #94BFF3; }
 .module             { color: #AFD8AF; }
 .variable           { color: #DCDCCC; }
@@ -51,6 +53,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
     <span class="macro">println!</span>(<span class="string_literal">"</span><span class="format_specifier">{</span><span class="variable">argument</span><span class="format_specifier">}</span><span class="string_literal">"</span>, argument = <span class="string_literal">"test"</span>);   <span class="comment">// =&gt; "test"</span>
     <span class="macro">println!</span>(<span class="string_literal">"</span><span class="format_specifier">{</span><span class="variable">name</span><span class="format_specifier">}</span><span class="string_literal"> </span><span class="format_specifier">{</span><span class="format_specifier">}</span><span class="string_literal">"</span>, <span class="numeric_literal">1</span>, name = <span class="numeric_literal">2</span>);          <span class="comment">// =&gt; "2 1"</span>
     <span class="macro">println!</span>(<span class="string_literal">"</span><span class="format_specifier">{</span><span class="variable">a</span><span class="format_specifier">}</span><span class="string_literal"> </span><span class="format_specifier">{</span><span class="variable">c</span><span class="format_specifier">}</span><span class="string_literal"> </span><span class="format_specifier">{</span><span class="variable">b</span><span class="format_specifier">}</span><span class="string_literal">"</span>, a=<span class="string_literal">"a"</span>, b=<span class="char_literal">'b'</span>, c=<span class="numeric_literal">3</span>);  <span class="comment">// =&gt; "a 3 b"</span>
+    <span class="macro">println!</span>(<span class="string_literal">"{{</span><span class="format_specifier">{</span><span class="format_specifier">}</span><span class="string_literal">}}"</span>, <span class="numeric_literal">2</span>);                       <span class="comment">// =&gt; "{2}"</span>
     <span class="macro">println!</span>(<span class="string_literal">"Hello </span><span class="format_specifier">{</span><span class="format_specifier">:</span><span class="numeric_literal">5</span><span class="format_specifier">}</span><span class="string_literal">!"</span>, <span class="string_literal">"x"</span>);
     <span class="macro">println!</span>(<span class="string_literal">"Hello </span><span class="format_specifier">{</span><span class="format_specifier">:</span><span class="numeric_literal">1</span><span class="format_specifier">$</span><span class="format_specifier">}</span><span class="string_literal">!"</span>, <span class="string_literal">"x"</span>, <span class="numeric_literal">5</span>);
     <span class="macro">println!</span>(<span class="string_literal">"Hello </span><span class="format_specifier">{</span><span class="numeric_literal">1</span><span class="format_specifier">:</span><span class="numeric_literal">0</span><span class="format_specifier">$</span><span class="format_specifier">}</span><span class="string_literal">!"</span>, <span class="numeric_literal">5</span>, <span class="string_literal">"x"</span>);
diff --git a/crates/ra_ide/src/snapshots/highlight_unsafe.html b/crates/ra_ide/src/snapshots/highlight_unsafe.html
new file mode 100644
index 000000000..17ffc727c
--- /dev/null
+++ b/crates/ra_ide/src/snapshots/highlight_unsafe.html
@@ -0,0 +1,48 @@
+
+<style>
+body                { margin: 0; }
+pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padding: 0.4em; }
+
+.lifetime           { color: #DFAF8F; font-style: italic; }
+.comment            { color: #7F9F7F; }
+.struct, .enum      { color: #7CB8BB; }
+.enum_variant       { color: #BDE0F3; }
+.string_literal     { color: #CC9393; }
+.field              { color: #94BFF3; }
+.function           { color: #93E0E3; }
+.operator.unsafe    { color: #E28C14; }
+.parameter          { color: #94BFF3; }
+.text               { color: #DCDCCC; }
+.type               { color: #7CB8BB; }
+.builtin_type       { color: #8CD0D3; }
+.type_param         { color: #DFAF8F; }
+.attribute          { color: #94BFF3; }
+.numeric_literal    { color: #BFEBBF; }
+.bool_literal       { color: #BFE6EB; }
+.macro              { color: #94BFF3; }
+.module             { color: #AFD8AF; }
+.variable           { color: #DCDCCC; }
+.format_specifier   { color: #CC696B; }
+.mutable            { text-decoration: underline; }
+
+.keyword            { color: #F0DFAF; font-weight: bold; }
+.keyword.unsafe     { color: #BC8383; font-weight: bold; }
+.control            { font-style: italic; }
+</style>
+<pre><code><span class="keyword unsafe">unsafe</span> <span class="keyword">fn</span> <span class="function declaration unsafe">unsafe_fn</span>() {}
+
+<span class="keyword">struct</span> <span class="struct declaration">HasUnsafeFn</span>;
+
+<span class="keyword">impl</span> <span class="struct">HasUnsafeFn</span> {
+    <span class="keyword unsafe">unsafe</span> <span class="keyword">fn</span> <span class="function declaration unsafe">unsafe_method</span>(&<span class="self_keyword">self</span>) {}
+}
+
+<span class="keyword">fn</span> <span class="function declaration">main</span>() {
+    <span class="keyword">let</span> <span class="variable declaration">x</span> = &<span class="numeric_literal">5</span> <span class="keyword">as</span> *<span class="keyword">const</span> <span class="builtin_type">usize</span>;
+    <span class="keyword unsafe">unsafe</span> {
+        <span class="function unsafe">unsafe_fn</span>();
+        <span class="struct">HasUnsafeFn</span>.<span class="function unsafe">unsafe_method</span>();
+        <span class="keyword">let</span> <span class="variable declaration">y</span> = <span class="operator unsafe">*</span><span class="variable">x</span>;
+        <span class="keyword">let</span> <span class="variable declaration">z</span> = -<span class="variable">x</span>;
+    }
+}</code></pre>
\ No newline at end of file
diff --git a/crates/ra_ide/src/snapshots/highlighting.html b/crates/ra_ide/src/snapshots/highlighting.html
index 635fe5cf9..42c5f3e55 100644
--- a/crates/ra_ide/src/snapshots/highlighting.html
+++ b/crates/ra_ide/src/snapshots/highlighting.html
@@ -10,6 +10,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .string_literal     { color: #CC9393; }
 .field              { color: #94BFF3; }
 .function           { color: #93E0E3; }
+.operator.unsafe    { color: #E28C14; }
 .parameter          { color: #94BFF3; }
 .text               { color: #DCDCCC; }
 .type               { color: #7CB8BB; }
@@ -17,6 +18,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .type_param         { color: #DFAF8F; }
 .attribute          { color: #94BFF3; }
 .numeric_literal    { color: #BFEBBF; }
+.bool_literal       { color: #BFE6EB; }
 .macro              { color: #94BFF3; }
 .module             { color: #AFD8AF; }
 .variable           { color: #DCDCCC; }
@@ -27,19 +29,19 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .keyword.unsafe     { color: #BC8383; font-weight: bold; }
 .control            { font-style: italic; }
 </style>
-<pre><code><span class="attribute">#[derive(Clone, Debug)]</span>
+<pre><code><span class="attribute">#[</span><span class="function attribute">derive</span><span class="attribute">(Clone, Debug)]</span>
 <span class="keyword">struct</span> <span class="struct declaration">Foo</span> {
     <span class="keyword">pub</span> <span class="field declaration">x</span>: <span class="builtin_type">i32</span>,
     <span class="keyword">pub</span> <span class="field declaration">y</span>: <span class="builtin_type">i32</span>,
 }
 
 <span class="keyword">trait</span> <span class="trait declaration">Bar</span> {
-    <span class="keyword">fn</span> <span class="function declaration">bar</span>(&<span class="keyword">self</span>) -&gt; <span class="builtin_type">i32</span>;
+    <span class="keyword">fn</span> <span class="function declaration">bar</span>(&<span class="self_keyword">self</span>) -&gt; <span class="builtin_type">i32</span>;
 }
 
 <span class="keyword">impl</span> <span class="trait">Bar</span> <span class="keyword">for</span> <span class="struct">Foo</span> {
-    <span class="keyword">fn</span> <span class="function declaration">bar</span>(&<span class="keyword">self</span>) -&gt; <span class="builtin_type">i32</span> {
-        <span class="keyword">self</span>.<span class="field">x</span>
+    <span class="keyword">fn</span> <span class="function declaration">bar</span>(&<span class="self_keyword">self</span>) -&gt; <span class="builtin_type">i32</span> {
+        <span class="self_keyword">self</span>.<span class="field">x</span>
     }
 }
 
@@ -64,7 +66,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
     <span class="macro">println!</span>(<span class="string_literal">"Hello, {}!"</span>, <span class="numeric_literal">92</span>);
 
     <span class="keyword">let</span> <span class="keyword">mut</span> <span class="variable declaration mutable">vec</span> = <span class="unresolved_reference">Vec</span>::<span class="unresolved_reference">new</span>();
-    <span class="keyword control">if</span> <span class="keyword">true</span> {
+    <span class="keyword control">if</span> <span class="bool_literal">true</span> {
         <span class="keyword">let</span> <span class="variable declaration">x</span> = <span class="numeric_literal">92</span>;
         <span class="variable mutable">vec</span>.<span class="unresolved_reference">push</span>(<span class="struct">Foo</span> { <span class="field">x</span>, <span class="field">y</span>: <span class="numeric_literal">1</span> });
     }
@@ -91,7 +93,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 <span class="keyword">use</span> <span class="enum">Option</span>::*;
 
 <span class="keyword">impl</span>&lt;<span class="type_param declaration">T</span>&gt; <span class="enum">Option</span>&lt;<span class="type_param">T</span>&gt; {
-    <span class="keyword">fn</span> <span class="function declaration">and</span>&lt;<span class="type_param declaration">U</span>&gt;(<span class="keyword">self</span>, <span class="variable declaration">other</span>: <span class="enum">Option</span>&lt;<span class="type_param">U</span>&gt;) -&gt; <span class="enum">Option</span>&lt;(<span class="type_param">T</span>, <span class="type_param">U</span>)&gt; {
+    <span class="keyword">fn</span> <span class="function declaration">and</span>&lt;<span class="type_param declaration">U</span>&gt;(<span class="self_keyword">self</span>, <span class="variable declaration">other</span>: <span class="enum">Option</span>&lt;<span class="type_param">U</span>&gt;) -&gt; <span class="enum">Option</span>&lt;(<span class="type_param">T</span>, <span class="type_param">U</span>)&gt; {
         <span class="keyword control">match</span> <span class="variable">other</span> {
             <span class="enum_variant">None</span> =&gt; <span class="macro">unimplemented!</span>(),
             <span class="variable declaration">Nope</span> =&gt; <span class="variable">Nope</span>,
diff --git a/crates/ra_ide/src/snapshots/rainbow_highlighting.html b/crates/ra_ide/src/snapshots/rainbow_highlighting.html
index 11e1f3e44..2dd61d20d 100644
--- a/crates/ra_ide/src/snapshots/rainbow_highlighting.html
+++ b/crates/ra_ide/src/snapshots/rainbow_highlighting.html
@@ -10,6 +10,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .string_literal     { color: #CC9393; }
 .field              { color: #94BFF3; }
 .function           { color: #93E0E3; }
+.operator.unsafe    { color: #E28C14; }
 .parameter          { color: #94BFF3; }
 .text               { color: #DCDCCC; }
 .type               { color: #7CB8BB; }
@@ -17,6 +18,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .type_param         { color: #DFAF8F; }
 .attribute          { color: #94BFF3; }
 .numeric_literal    { color: #BFEBBF; }
+.bool_literal       { color: #BFE6EB; }
 .macro              { color: #94BFF3; }
 .module             { color: #AFD8AF; }
 .variable           { color: #DCDCCC; }
diff --git a/crates/ra_ide/src/ssr.rs b/crates/ra_ide/src/ssr.rs
index 1873d1d0d..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,
@@ -196,10 +216,10 @@ fn find(pattern: &SsrPattern, code: &SyntaxNode) -> SsrMatches {
     ) -> Option<Match> {
         let match_ = check_opt_nodes(pattern.path(), code.path(), placeholders, match_)?;
 
-        let mut pattern_fields =
-            pattern.record_field_list().map(|x| x.fields().collect()).unwrap_or(vec![]);
-        let mut code_fields =
-            code.record_field_list().map(|x| x.fields().collect()).unwrap_or(vec![]);
+        let mut pattern_fields: Vec<RecordField> =
+            pattern.record_field_list().map(|x| x.fields().collect()).unwrap_or_default();
+        let mut code_fields: Vec<RecordField> =
+            code.record_field_list().map(|x| x.fields().collect()).unwrap_or_default();
 
         if pattern_fields.len() != code_fields.len() {
             return None;
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 be57eeb0a..19ecd54d6 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
@@ -361,7 +368,9 @@ fn highlight_element(
         }
 
         // Highlight references like the definitions they resolve to
-        NAME_REF if element.ancestors().any(|it| it.kind() == ATTR) => return None,
+        NAME_REF if element.ancestors().any(|it| it.kind() == ATTR) => {
+            Highlight::from(HighlightTag::Function) | HighlightModifier::Attribute
+        }
         NAME_REF => {
             let name_ref = element.into_node().and_then(ast::NameRef::cast).unwrap();
             match classify_name_ref(sema, &name_ref) {
@@ -389,6 +398,7 @@ fn highlight_element(
         INT_NUMBER | FLOAT_NUMBER => HighlightTag::NumericLiteral.into(),
         BYTE => HighlightTag::ByteLiteral.into(),
         CHAR => HighlightTag::CharLiteral.into(),
+        QUESTION => Highlight::new(HighlightTag::Operator) | HighlightModifier::ControlFlow,
         LIFETIME => {
             let h = Highlight::new(HighlightTag::Lifetime);
             match element.parent().map(|it| it.kind()) {
@@ -396,6 +406,23 @@ fn highlight_element(
                 _ => h,
             }
         }
+        PREFIX_EXPR => {
+            let prefix_expr = element.into_node().and_then(ast::PrefixExpr::cast)?;
+            match prefix_expr.op_kind() {
+                Some(ast::PrefixOp::Deref) => {}
+                _ => return None,
+            }
+
+            let expr = prefix_expr.expr()?;
+            let ty = sema.type_of_expr(&expr)?;
+            if !ty.is_raw_ptr() {
+                return None;
+            }
+
+            let mut h = Highlight::new(HighlightTag::Operator);
+            h |= HighlightModifier::Unsafe;
+            h
+        }
 
         k if k.is_keyword() => {
             let h = Highlight::new(HighlightTag::Keyword);
@@ -411,6 +438,8 @@ fn highlight_element(
                 | T![in] => h | HighlightModifier::ControlFlow,
                 T![for] if !is_child_of_impl(element) => h | HighlightModifier::ControlFlow,
                 T![unsafe] => h | HighlightModifier::Unsafe,
+                T![true] | T![false] => HighlightTag::BoolLiteral.into(),
+                T![self] => HighlightTag::SelfKeyword.into(),
                 _ => h,
             }
         }
@@ -446,7 +475,13 @@ fn highlight_name(db: &RootDatabase, def: Definition) -> Highlight {
         Definition::Field(_) => HighlightTag::Field,
         Definition::ModuleDef(def) => match def {
             hir::ModuleDef::Module(_) => HighlightTag::Module,
-            hir::ModuleDef::Function(_) => HighlightTag::Function,
+            hir::ModuleDef::Function(func) => {
+                let mut h = HighlightTag::Function.into();
+                if func.is_unsafe(db) {
+                    h |= HighlightModifier::Unsafe;
+                }
+                return h;
+            }
             hir::ModuleDef::Adt(hir::Adt::Struct(_)) => HighlightTag::Struct,
             hir::ModuleDef::Adt(hir::Adt::Enum(_)) => HighlightTag::Enum,
             hir::ModuleDef::Adt(hir::Adt::Union(_)) => HighlightTag::Union,
@@ -478,23 +513,31 @@ fn highlight_name(db: &RootDatabase, def: Definition) -> Highlight {
 }
 
 fn highlight_name_by_syntax(name: ast::Name) -> Highlight {
-    let default = HighlightTag::Function.into();
+    let default = HighlightTag::UnresolvedReference;
 
     let parent = match name.syntax().parent() {
         Some(it) => it,
-        _ => return default,
+        _ => return default.into(),
     };
 
-    match parent.kind() {
-        STRUCT_DEF => HighlightTag::Struct.into(),
-        ENUM_DEF => HighlightTag::Enum.into(),
-        UNION_DEF => HighlightTag::Union.into(),
-        TRAIT_DEF => HighlightTag::Trait.into(),
-        TYPE_ALIAS_DEF => HighlightTag::TypeAlias.into(),
-        TYPE_PARAM => HighlightTag::TypeParam.into(),
-        RECORD_FIELD_DEF => HighlightTag::Field.into(),
+    let tag = match parent.kind() {
+        STRUCT_DEF => HighlightTag::Struct,
+        ENUM_DEF => HighlightTag::Enum,
+        UNION_DEF => HighlightTag::Union,
+        TRAIT_DEF => HighlightTag::Trait,
+        TYPE_ALIAS_DEF => HighlightTag::TypeAlias,
+        TYPE_PARAM => HighlightTag::TypeParam,
+        RECORD_FIELD_DEF => HighlightTag::Field,
+        MODULE => HighlightTag::Module,
+        FN_DEF => HighlightTag::Function,
+        CONST_DEF => HighlightTag::Constant,
+        STATIC_DEF => HighlightTag::Static,
+        ENUM_VARIANT => HighlightTag::EnumVariant,
+        BIND_PAT => HighlightTag::Local,
         _ => default,
-    }
+    };
+
+    tag.into()
 }
 
 fn highlight_injection(
diff --git a/crates/ra_ide/src/syntax_highlighting/html.rs b/crates/ra_ide/src/syntax_highlighting/html.rs
index ff0eeeb52..7d946c98d 100644
--- a/crates/ra_ide/src/syntax_highlighting/html.rs
+++ b/crates/ra_ide/src/syntax_highlighting/html.rs
@@ -69,6 +69,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .string_literal     { color: #CC9393; }
 .field              { color: #94BFF3; }
 .function           { color: #93E0E3; }
+.operator.unsafe    { color: #E28C14; }
 .parameter          { color: #94BFF3; }
 .text               { color: #DCDCCC; }
 .type               { color: #7CB8BB; }
@@ -76,6 +77,7 @@ pre                 { color: #DCDCCC; background: #3F3F3F; font-size: 22px; padd
 .type_param         { color: #DFAF8F; }
 .attribute          { color: #94BFF3; }
 .numeric_literal    { color: #BFEBBF; }
+.bool_literal       { color: #BFE6EB; }
 .macro              { color: #94BFF3; }
 .module             { color: #AFD8AF; }
 .variable           { color: #DCDCCC; }
diff --git a/crates/ra_ide/src/syntax_highlighting/tags.rs b/crates/ra_ide/src/syntax_highlighting/tags.rs
index be1a0f12b..94f466966 100644
--- a/crates/ra_ide/src/syntax_highlighting/tags.rs
+++ b/crates/ra_ide/src/syntax_highlighting/tags.rs
@@ -15,6 +15,7 @@ pub struct HighlightModifiers(u32);
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum HighlightTag {
     Attribute,
+    BoolLiteral,
     BuiltinType,
     ByteLiteral,
     CharLiteral,
@@ -23,12 +24,15 @@ pub enum HighlightTag {
     Enum,
     EnumVariant,
     Field,
+    FormatSpecifier,
     Function,
     Keyword,
     Lifetime,
     Macro,
     Module,
     NumericLiteral,
+    Operator,
+    SelfKeyword,
     SelfType,
     Static,
     StringLiteral,
@@ -39,14 +43,15 @@ pub enum HighlightTag {
     Union,
     Local,
     UnresolvedReference,
-    FormatSpecifier,
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 #[repr(u8)]
 pub enum HighlightModifier {
+    /// Used to differentiate individual elements within attributes.
+    Attribute = 0,
     /// Used with keywords like `if` and `break`.
-    ControlFlow = 0,
+    ControlFlow,
     /// `foo` in `fn foo(x: i32)` is a definition, `foo` in `foo(90 + 2)` is
     /// not.
     Definition,
@@ -58,6 +63,7 @@ impl HighlightTag {
     fn as_str(self) -> &'static str {
         match self {
             HighlightTag::Attribute => "attribute",
+            HighlightTag::BoolLiteral => "bool_literal",
             HighlightTag::BuiltinType => "builtin_type",
             HighlightTag::ByteLiteral => "byte_literal",
             HighlightTag::CharLiteral => "char_literal",
@@ -66,12 +72,15 @@ impl HighlightTag {
             HighlightTag::Enum => "enum",
             HighlightTag::EnumVariant => "enum_variant",
             HighlightTag::Field => "field",
+            HighlightTag::FormatSpecifier => "format_specifier",
             HighlightTag::Function => "function",
             HighlightTag::Keyword => "keyword",
             HighlightTag::Lifetime => "lifetime",
             HighlightTag::Macro => "macro",
             HighlightTag::Module => "module",
             HighlightTag::NumericLiteral => "numeric_literal",
+            HighlightTag::Operator => "operator",
+            HighlightTag::SelfKeyword => "self_keyword",
             HighlightTag::SelfType => "self_type",
             HighlightTag::Static => "static",
             HighlightTag::StringLiteral => "string_literal",
@@ -82,7 +91,6 @@ impl HighlightTag {
             HighlightTag::Union => "union",
             HighlightTag::Local => "variable",
             HighlightTag::UnresolvedReference => "unresolved_reference",
-            HighlightTag::FormatSpecifier => "format_specifier",
         }
     }
 }
@@ -95,6 +103,7 @@ impl fmt::Display for HighlightTag {
 
 impl HighlightModifier {
     const ALL: &'static [HighlightModifier] = &[
+        HighlightModifier::Attribute,
         HighlightModifier::ControlFlow,
         HighlightModifier::Definition,
         HighlightModifier::Mutable,
@@ -103,6 +112,7 @@ impl HighlightModifier {
 
     fn as_str(self) -> &'static str {
         match self {
+            HighlightModifier::Attribute => "attribute",
             HighlightModifier::ControlFlow => "control",
             HighlightModifier::Definition => "declaration",
             HighlightModifier::Mutable => "mutable",
diff --git a/crates/ra_ide/src/syntax_highlighting/tests.rs b/crates/ra_ide/src/syntax_highlighting/tests.rs
index eb43a23da..36a1aa419 100644
--- a/crates/ra_ide/src/syntax_highlighting/tests.rs
+++ b/crates/ra_ide/src/syntax_highlighting/tests.rs
@@ -218,6 +218,7 @@ fn main() {
     println!("{argument}", argument = "test");   // => "test"
     println!("{name} {}", 1, name = 2);          // => "2 1"
     println!("{a} {c} {b}", a="a", b='b', c=3);  // => "a 3 b"
+    println!("{{{}}}", 2);                       // => "{2}"
     println!("Hello {:5}!", "x");
     println!("Hello {:1$}!", "x", 5);
     println!("Hello {1:0$}!", 5, "x");
@@ -257,3 +258,34 @@ fn main() {
     fs::write(dst_file, &actual_html).unwrap();
     assert_eq_text!(expected_html, actual_html);
 }
+
+#[test]
+fn test_unsafe_highlighting() {
+    let (analysis, file_id) = single_file(
+        r#"
+unsafe fn unsafe_fn() {}
+
+struct HasUnsafeFn;
+
+impl HasUnsafeFn {
+    unsafe fn unsafe_method(&self) {}
+}
+
+fn main() {
+    let x = &5 as *const usize;
+    unsafe {
+        unsafe_fn();
+        HasUnsafeFn.unsafe_method();
+        let y = *x;
+        let z = -x;
+    }
+}
+"#
+        .trim(),
+    );
+    let dst_file = project_dir().join("crates/ra_ide/src/snapshots/highlight_unsafe.html");
+    let actual_html = &analysis.highlight_as_html(file_id, false).unwrap();
+    let expected_html = &read_text(&dst_file);
+    fs::write(dst_file, &actual_html).unwrap();
+    assert_eq_text!(expected_html, actual_html);
+}
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/src/typing/on_enter.rs b/crates/ra_ide/src/typing/on_enter.rs
index e7d64b4f6..a40d8af9c 100644
--- a/crates/ra_ide/src/typing/on_enter.rs
+++ b/crates/ra_ide/src/typing/on_enter.rs
@@ -11,9 +11,7 @@ use ra_syntax::{
 };
 use ra_text_edit::TextEdit;
 
-use crate::{SourceChange, SourceFileEdit};
-
-pub(crate) fn on_enter(db: &RootDatabase, position: FilePosition) -> Option<SourceChange> {
+pub(crate) fn on_enter(db: &RootDatabase, position: FilePosition) -> Option<TextEdit> {
     let parse = db.parse(position.file_id);
     let file = parse.tree();
     let comment = file
@@ -41,9 +39,7 @@ pub(crate) fn on_enter(db: &RootDatabase, position: FilePosition) -> Option<Sour
     let inserted = format!("\n{}{} $0", indent, prefix);
     let edit = TextEdit::insert(position.offset, inserted);
 
-    let mut res = SourceChange::from(SourceFileEdit { edit, file_id: position.file_id });
-    res.is_snippet = true;
-    Some(res)
+    Some(edit)
 }
 
 fn followed_by_comment(comment: &ast::Comment) -> bool {
@@ -90,9 +86,8 @@ mod tests {
         let (analysis, file_id) = single_file(&before);
         let result = analysis.on_enter(FilePosition { offset, file_id }).unwrap()?;
 
-        assert_eq!(result.source_file_edits.len(), 1);
         let mut actual = before.to_string();
-        result.source_file_edits[0].edit.apply(&mut actual);
+        result.apply(&mut actual);
         Some(actual)
     }