91 files changed, 3737 insertions, 2021 deletions

diff --git a/.gitignore b/.gitignore
index f835edef0..dab51647d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,4 +7,4 @@ crates/*/target
 *.log
 *.iml
 .vscode/settings.json
-cargo-timing*.html
+*.html
diff --git a/Cargo.lock b/Cargo.lock
index 1159d0f1d..af27bfc85 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -112,17 +112,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822"
 
 [[package]]
-name = "chalk-base"
-version = "0.10.1-dev"
-source = "git+https://github.com/rust-lang/chalk.git?rev=5a3b871ca17529ab5aa5787594fabad1634936cb#5a3b871ca17529ab5aa5787594fabad1634936cb"
-dependencies = [
- "lazy_static",
-]
-
-[[package]]
 name = "chalk-derive"
 version = "0.10.1-dev"
-source = "git+https://github.com/rust-lang/chalk.git?rev=5a3b871ca17529ab5aa5787594fabad1634936cb#5a3b871ca17529ab5aa5787594fabad1634936cb"
+source = "git+https://github.com/rust-lang/chalk.git?rev=329b7f3fdd2431ed6f6778cde53f22374c7d094c#329b7f3fdd2431ed6f6778cde53f22374c7d094c"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -133,9 +125,8 @@ dependencies = [
 [[package]]
 name = "chalk-engine"
 version = "0.10.1-dev"
-source = "git+https://github.com/rust-lang/chalk.git?rev=5a3b871ca17529ab5aa5787594fabad1634936cb#5a3b871ca17529ab5aa5787594fabad1634936cb"
+source = "git+https://github.com/rust-lang/chalk.git?rev=329b7f3fdd2431ed6f6778cde53f22374c7d094c#329b7f3fdd2431ed6f6778cde53f22374c7d094c"
 dependencies = [
- "chalk-base",
  "chalk-derive",
  "chalk-ir",
  "rustc-hash",
@@ -144,18 +135,17 @@ dependencies = [
 [[package]]
 name = "chalk-ir"
 version = "0.10.1-dev"
-source = "git+https://github.com/rust-lang/chalk.git?rev=5a3b871ca17529ab5aa5787594fabad1634936cb#5a3b871ca17529ab5aa5787594fabad1634936cb"
+source = "git+https://github.com/rust-lang/chalk.git?rev=329b7f3fdd2431ed6f6778cde53f22374c7d094c#329b7f3fdd2431ed6f6778cde53f22374c7d094c"
 dependencies = [
- "chalk-base",
  "chalk-derive",
+ "lazy_static",
 ]
 
 [[package]]
 name = "chalk-solve"
 version = "0.10.1-dev"
-source = "git+https://github.com/rust-lang/chalk.git?rev=5a3b871ca17529ab5aa5787594fabad1634936cb#5a3b871ca17529ab5aa5787594fabad1634936cb"
+source = "git+https://github.com/rust-lang/chalk.git?rev=329b7f3fdd2431ed6f6778cde53f22374c7d094c#329b7f3fdd2431ed6f6778cde53f22374c7d094c"
 dependencies = [
- "chalk-base",
  "chalk-derive",
  "chalk-engine",
  "chalk-ir",
@@ -253,9 +243,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-queue"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c695eeca1e7173472a32221542ae469b3e9aac3a4fc81f7696bcad82029493db"
+checksum = "ab6bffe714b6bb07e42f201352c34f51fefd355ace793f9e638ebd52d23f98d2"
 dependencies = [
  "cfg-if",
  "crossbeam-utils",
@@ -650,9 +640,9 @@ dependencies = [
 
 [[package]]
 name = "lsp-types"
-version = "0.74.1"
+version = "0.74.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57c0e6a2b8837d27b29deb3f3e6dc1c6d2f57947677f9be1024e482ec5b59525"
+checksum = "b360754e89e0e13c114245131382ba921d4ff1efabb918e549422938aaa8d392"
 dependencies = [
  "base64",
  "bitflags",
@@ -819,9 +809,9 @@ dependencies = [
 
 [[package]]
 name = "paste"
-version = "0.1.14"
+version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3431e8f72b90f8a7af91dec890d9814000cb371258e0ec7370d93e085361f531"
+checksum = "d53181dcd37421c08d3b69f887784956674d09c3f9a47a04fece2b130a5b346b"
 dependencies = [
  "paste-impl",
  "proc-macro-hack",
@@ -829,9 +819,9 @@ dependencies = [
 
 [[package]]
 name = "paste-impl"
-version = "0.1.14"
+version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "25af5fc872ba284d8d84608bf8a0fa9b5376c96c23f503b007dfd9e34dde5606"
+checksum = "05ca490fa1c034a71412b4d1edcb904ec5a0981a4426c9eb2128c0fda7a68d17"
 dependencies = [
  "proc-macro-hack",
  "proc-macro2",
@@ -1129,6 +1119,7 @@ dependencies = [
  "memmap",
  "ra_mbe",
  "ra_proc_macro",
+ "ra_toolchain",
  "ra_tt",
  "serde_derive",
  "test_utils",
@@ -1301,9 +1292,9 @@ checksum = "2439c63f3f6139d1b57529d16bc3b8bb855230c8efcc5d3a896c8bea7c3b1e84"
 
 [[package]]
 name = "regex"
-version = "1.3.7"
+version = "1.3.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6020f034922e3194c711b82a627453881bc4682166cabb07134a10c26ba7692"
+checksum = "9c3780fcf44b193bc4d09f36d2a3c87b251da4a046c87795a0d35f4f927ad8e6"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -1313,9 +1304,9 @@ dependencies = [
 
 [[package]]
 name = "regex-syntax"
-version = "0.6.17"
+version = "0.6.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fe5bd57d1d7414c6b5ed48563a2c855d995ff777729dcd91c369ec7fea395ae"
+checksum = "26412eb97c6b088a6997e05f69403a802a92d520de2f8e63c2b65f9e0f47c4e8"
 
 [[package]]
 name = "relative-path"
@@ -1501,18 +1492,18 @@ checksum = "388a1df253eca08550bef6c72392cfe7c30914bf41df5269b68cbd6ff8f570a3"
 
 [[package]]
 name = "serde"
-version = "1.0.110"
+version = "1.0.111"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "99e7b308464d16b56eba9964e4972a3eee817760ab60d88c3f86e1fecb08204c"
+checksum = "c9124df5b40cbd380080b2cc6ab894c040a3070d995f5c9dc77e18c34a8ae37d"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.110"
+version = "1.0.111"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "818fbf6bfa9a42d3bfcaca148547aa00c7b915bec71d1757aa2d44ca68771984"
+checksum = "3f2c3ac8e6ca1e9c80b8be1023940162bf81ae3cffbb1809474152f2ce1eb250"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1586,9 +1577,9 @@ checksum = "ab16ced94dbd8a46c82fd81e3ed9a8727dac2977ea869d217bcc4ea1f122e81f"
 
 [[package]]
 name = "syn"
-version = "1.0.25"
+version = "1.0.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f14a640819f79b72a710c0be059dce779f9339ae046c8bef12c361d56702146f"
+checksum = "bb37da98a55b1d08529362d9cbb863be17556873df2585904ab9d2bc951291d0"
 dependencies = [
  "proc-macro2",
  "quote",
diff --git a/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs b/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs
index 6a675e812..776bddf91 100644
--- a/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs
+++ b/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs
@@ -4,9 +4,9 @@ use test_utils::mark;
 
 use crate::{utils::FamousDefs, AssistContext, AssistId, Assists};
 
-// Assist add_from_impl_for_enum
+// Assist: add_from_impl_for_enum
 //
-// Adds a From impl for an enum variant with one tuple field
+// Adds a From impl for an enum variant with one tuple field.
 //
 // ```
 // enum A { <|>One(u32) }
diff --git a/crates/ra_assists/src/handlers/introduce_named_lifetime.rs b/crates/ra_assists/src/handlers/introduce_named_lifetime.rs
new file mode 100644
index 000000000..beb5b7366
--- /dev/null
+++ b/crates/ra_assists/src/handlers/introduce_named_lifetime.rs
@@ -0,0 +1,303 @@
+use ra_syntax::{
+    ast::{self, NameOwner, TypeAscriptionOwner, TypeParamsOwner},
+    AstNode, SyntaxKind, TextRange, TextSize,
+};
+use rustc_hash::FxHashSet;
+
+use crate::{assist_context::AssistBuilder, AssistContext, AssistId, Assists};
+
+static ASSIST_NAME: &str = "introduce_named_lifetime";
+static ASSIST_LABEL: &str = "Introduce named lifetime";
+
+// Assist: introduce_named_lifetime
+//
+// Change an anonymous lifetime to a named lifetime.
+//
+// ```
+// impl Cursor<'_<|>> {
+//     fn node(self) -> &SyntaxNode {
+//         match self {
+//             Cursor::Replace(node) | Cursor::Before(node) => node,
+//         }
+//     }
+// }
+// ```
+// ->
+// ```
+// impl<'a> Cursor<'a> {
+//     fn node(self) -> &SyntaxNode {
+//         match self {
+//             Cursor::Replace(node) | Cursor::Before(node) => node,
+//         }
+//     }
+// }
+// ```
+// FIXME: How can we handle renaming any one of multiple anonymous lifetimes?
+// FIXME: should also add support for the case fun(f: &Foo) -> &<|>Foo
+pub(crate) fn introduce_named_lifetime(acc: &mut Assists, ctx: &AssistContext) -> Option<()> {
+    let lifetime_token = ctx
+        .find_token_at_offset(SyntaxKind::LIFETIME)
+        .filter(|lifetime| lifetime.text() == "'_")?;
+    if let Some(fn_def) = lifetime_token.ancestors().find_map(ast::FnDef::cast) {
+        generate_fn_def_assist(acc, &fn_def, lifetime_token.text_range())
+    } else if let Some(impl_def) = lifetime_token.ancestors().find_map(ast::ImplDef::cast) {
+        // only allow naming the last anonymous lifetime
+        lifetime_token.next_token().filter(|tok| tok.kind() == SyntaxKind::R_ANGLE)?;
+        generate_impl_def_assist(acc, &impl_def, lifetime_token.text_range())
+    } else {
+        None
+    }
+}
+
+/// Generate the assist for the fn def case
+fn generate_fn_def_assist(
+    acc: &mut Assists,
+    fn_def: &ast::FnDef,
+    lifetime_loc: TextRange,
+) -> Option<()> {
+    let param_list: ast::ParamList = fn_def.param_list()?;
+    let new_lifetime_param = generate_unique_lifetime_param_name(&fn_def.type_param_list())?;
+    let end_of_fn_ident = fn_def.name()?.ident_token()?.text_range().end();
+    let self_param =
+        // use the self if it's a reference and has no explicit lifetime
+        param_list.self_param().filter(|p| p.lifetime_token().is_none() && p.amp_token().is_some());
+    // compute the location which implicitly has the same lifetime as the anonymous lifetime
+    let loc_needing_lifetime = if let Some(self_param) = self_param {
+        // if we have a self reference, use that
+        Some(self_param.self_token()?.text_range().start())
+    } else {
+        // otherwise, if there's a single reference parameter without a named liftime, use that
+        let fn_params_without_lifetime: Vec<_> = param_list
+            .params()
+            .filter_map(|param| match param.ascribed_type() {
+                Some(ast::TypeRef::ReferenceType(ascribed_type))
+                    if ascribed_type.lifetime_token() == None =>
+                {
+                    Some(ascribed_type.amp_token()?.text_range().end())
+                }
+                _ => None,
+            })
+            .collect();
+        match fn_params_without_lifetime.len() {
+            1 => Some(fn_params_without_lifetime.into_iter().nth(0)?),
+            0 => None,
+            // multiple unnnamed is invalid. assist is not applicable
+            _ => return None,
+        }
+    };
+    acc.add(AssistId(ASSIST_NAME), ASSIST_LABEL, lifetime_loc, |builder| {
+        add_lifetime_param(fn_def, builder, end_of_fn_ident, new_lifetime_param);
+        builder.replace(lifetime_loc, format!("'{}", new_lifetime_param));
+        loc_needing_lifetime.map(|loc| builder.insert(loc, format!("'{} ", new_lifetime_param)));
+    })
+}
+
+/// Generate the assist for the impl def case
+fn generate_impl_def_assist(
+    acc: &mut Assists,
+    impl_def: &ast::ImplDef,
+    lifetime_loc: TextRange,
+) -> Option<()> {
+    let new_lifetime_param = generate_unique_lifetime_param_name(&impl_def.type_param_list())?;
+    let end_of_impl_kw = impl_def.impl_token()?.text_range().end();
+    acc.add(AssistId(ASSIST_NAME), ASSIST_LABEL, lifetime_loc, |builder| {
+        add_lifetime_param(impl_def, builder, end_of_impl_kw, new_lifetime_param);
+        builder.replace(lifetime_loc, format!("'{}", new_lifetime_param));
+    })
+}
+
+/// Given a type parameter list, generate a unique lifetime parameter name
+/// which is not in the list
+fn generate_unique_lifetime_param_name(
+    existing_type_param_list: &Option<ast::TypeParamList>,
+) -> Option<char> {
+    match existing_type_param_list {
+        Some(type_params) => {
+            let used_lifetime_params: FxHashSet<_> = type_params
+                .lifetime_params()
+                .map(|p| p.syntax().text().to_string()[1..].to_owned())
+                .collect();
+            (b'a'..=b'z').map(char::from).find(|c| !used_lifetime_params.contains(&c.to_string()))
+        }
+        None => Some('a'),
+    }
+}
+
+/// Add the lifetime param to `builder`. If there are type parameters in `type_params_owner`, add it to the end. Otherwise
+/// add new type params brackets with the lifetime parameter at `new_type_params_loc`.
+fn add_lifetime_param<TypeParamsOwner: ast::TypeParamsOwner>(
+    type_params_owner: &TypeParamsOwner,
+    builder: &mut AssistBuilder,
+    new_type_params_loc: TextSize,
+    new_lifetime_param: char,
+) {
+    match type_params_owner.type_param_list() {
+        // add the new lifetime parameter to an existing type param list
+        Some(type_params) => {
+            builder.insert(
+                (u32::from(type_params.syntax().text_range().end()) - 1).into(),
+                format!(", '{}", new_lifetime_param),
+            );
+        }
+        // create a new type param list containing only the new lifetime parameter
+        None => {
+            builder.insert(new_type_params_loc, format!("<'{}>", new_lifetime_param));
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::tests::{check_assist, check_assist_not_applicable};
+
+    #[test]
+    fn test_example_case() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"impl Cursor<'_<|>> {
+                fn node(self) -> &SyntaxNode {
+                    match self {
+                        Cursor::Replace(node) | Cursor::Before(node) => node,
+                    }
+                }
+            }"#,
+            r#"impl<'a> Cursor<'a> {
+                fn node(self) -> &SyntaxNode {
+                    match self {
+                        Cursor::Replace(node) | Cursor::Before(node) => node,
+                    }
+                }
+            }"#,
+        );
+    }
+
+    #[test]
+    fn test_example_case_simplified() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"impl Cursor<'_<|>> {"#,
+            r#"impl<'a> Cursor<'a> {"#,
+        );
+    }
+
+    #[test]
+    fn test_example_case_cursor_after_tick() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"impl Cursor<'<|>_> {"#,
+            r#"impl<'a> Cursor<'a> {"#,
+        );
+    }
+
+    #[test]
+    fn test_example_case_cursor_before_tick() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"impl Cursor<<|>'_> {"#,
+            r#"impl<'a> Cursor<'a> {"#,
+        );
+    }
+
+    #[test]
+    fn test_not_applicable_cursor_position() {
+        check_assist_not_applicable(introduce_named_lifetime, r#"impl Cursor<'_><|> {"#);
+        check_assist_not_applicable(introduce_named_lifetime, r#"impl Cursor<|><'_> {"#);
+    }
+
+    #[test]
+    fn test_not_applicable_lifetime_already_name() {
+        check_assist_not_applicable(introduce_named_lifetime, r#"impl Cursor<'a<|>> {"#);
+        check_assist_not_applicable(introduce_named_lifetime, r#"fn my_fun<'a>() -> X<'a<|>>"#);
+    }
+
+    #[test]
+    fn test_with_type_parameter() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"impl<T> Cursor<T, '_<|>>"#,
+            r#"impl<T, 'a> Cursor<T, 'a>"#,
+        );
+    }
+
+    #[test]
+    fn test_with_existing_lifetime_name_conflict() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"impl<'a, 'b> Cursor<'a, 'b, '_<|>>"#,
+            r#"impl<'a, 'b, 'c> Cursor<'a, 'b, 'c>"#,
+        );
+    }
+
+    #[test]
+    fn test_function_return_value_anon_lifetime_param() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun() -> X<'_<|>>"#,
+            r#"fn my_fun<'a>() -> X<'a>"#,
+        );
+    }
+
+    #[test]
+    fn test_function_return_value_anon_reference_lifetime() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun() -> &'_<|> X"#,
+            r#"fn my_fun<'a>() -> &'a X"#,
+        );
+    }
+
+    #[test]
+    fn test_function_param_anon_lifetime() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun(x: X<'_<|>>)"#,
+            r#"fn my_fun<'a>(x: X<'a>)"#,
+        );
+    }
+
+    #[test]
+    fn test_function_add_lifetime_to_params() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun(f: &Foo) -> X<'_<|>>"#,
+            r#"fn my_fun<'a>(f: &'a Foo) -> X<'a>"#,
+        );
+    }
+
+    #[test]
+    fn test_function_add_lifetime_to_params_in_presence_of_other_lifetime() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun<'other>(f: &Foo, b: &'other Bar) -> X<'_<|>>"#,
+            r#"fn my_fun<'other, 'a>(f: &'a Foo, b: &'other Bar) -> X<'a>"#,
+        );
+    }
+
+    #[test]
+    fn test_function_not_applicable_without_self_and_multiple_unnamed_param_lifetimes() {
+        // this is not permitted under lifetime elision rules
+        check_assist_not_applicable(
+            introduce_named_lifetime,
+            r#"fn my_fun(f: &Foo, b: &Bar) -> X<'_<|>>"#,
+        );
+    }
+
+    #[test]
+    fn test_function_add_lifetime_to_self_ref_param() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun<'other>(&self, f: &Foo, b: &'other Bar) -> X<'_<|>>"#,
+            r#"fn my_fun<'other, 'a>(&'a self, f: &Foo, b: &'other Bar) -> X<'a>"#,
+        );
+    }
+
+    #[test]
+    fn test_function_add_lifetime_to_param_with_non_ref_self() {
+        check_assist(
+            introduce_named_lifetime,
+            r#"fn my_fun<'other>(self, f: &Foo, b: &'other Bar) -> X<'_<|>>"#,
+            r#"fn my_fun<'other, 'a>(self, f: &'a Foo, b: &'other Bar) -> X<'a>"#,
+        );
+    }
+}
diff --git a/crates/ra_assists/src/lib.rs b/crates/ra_assists/src/lib.rs
index 464bc03dd..fb5d59a87 100644
--- a/crates/ra_assists/src/lib.rs
+++ b/crates/ra_assists/src/lib.rs
@@ -121,6 +121,7 @@ mod handlers {
     mod flip_comma;
     mod flip_trait_bound;
     mod inline_local_variable;
+    mod introduce_named_lifetime;
     mod introduce_variable;
     mod invert_if;
     mod merge_imports;
@@ -160,6 +161,7 @@ mod handlers {
             flip_comma::flip_comma,
             flip_trait_bound::flip_trait_bound,
             inline_local_variable::inline_local_variable,
+            introduce_named_lifetime::introduce_named_lifetime,
             introduce_variable::introduce_variable,
             invert_if::invert_if,
             merge_imports::merge_imports,
diff --git a/crates/ra_assists/src/tests/generated.rs b/crates/ra_assists/src/tests/generated.rs
index 250e56a69..d17504529 100644
--- a/crates/ra_assists/src/tests/generated.rs
+++ b/crates/ra_assists/src/tests/generated.rs
@@ -59,6 +59,25 @@ fn main() {
 }
 
 #[test]
+fn doctest_add_from_impl_for_enum() {
+    check_doc_test(
+        "add_from_impl_for_enum",
+        r#####"
+enum A { <|>One(u32) }
+"#####,
+        r#####"
+enum A { One(u32) }
+
+impl From<u32> for A {
+    fn from(v: u32) -> Self {
+        A::One(v)
+    }
+}
+"#####,
+    )
+}
+
+#[test]
 fn doctest_add_function() {
     check_doc_test(
         "add_function",
@@ -433,6 +452,31 @@ fn main() {
 }
 
 #[test]
+fn doctest_introduce_named_lifetime() {
+    check_doc_test(
+        "introduce_named_lifetime",
+        r#####"
+impl Cursor<'_<|>> {
+    fn node(self) -> &SyntaxNode {
+        match self {
+            Cursor::Replace(node) | Cursor::Before(node) => node,
+        }
+    }
+}
+"#####,
+        r#####"
+impl<'a> Cursor<'a> {
+    fn node(self) -> &SyntaxNode {
+        match self {
+            Cursor::Replace(node) | Cursor::Before(node) => node,
+        }
+    }
+}
+"#####,
+    )
+}
+
+#[test]
 fn doctest_introduce_variable() {
     check_doc_test(
         "introduce_variable",
diff --git a/crates/ra_hir/src/code_model.rs b/crates/ra_hir/src/code_model.rs
index e40aeffbc..4a06f3bcd 100644
--- a/crates/ra_hir/src/code_model.rs
+++ b/crates/ra_hir/src/code_model.rs
@@ -637,6 +637,10 @@ impl Function {
         db.function_data(self.id).params.clone()
     }
 
+    pub fn is_unsafe(self, db: &dyn HirDatabase) -> bool {
+        db.function_data(self.id).is_unsafe
+    }
+
     pub fn diagnostics(self, db: &dyn HirDatabase, sink: &mut DiagnosticSink) {
         let _p = profile("Function::diagnostics");
         let infer = db.infer(self.id.into());
@@ -1190,6 +1194,10 @@ impl Type {
         )
     }
 
+    pub fn is_raw_ptr(&self) -> bool {
+        matches!(&self.ty.value, Ty::Apply(ApplicationTy { ctor: TypeCtor::RawPtr(..), .. }))
+    }
+
     pub fn contains_unknown(&self) -> bool {
         return go(&self.ty.value);
 
diff --git a/crates/ra_hir_def/src/body/lower.rs b/crates/ra_hir_def/src/body/lower.rs
index 905c0cf5d..f159f80af 100644
--- a/crates/ra_hir_def/src/body/lower.rs
+++ b/crates/ra_hir_def/src/body/lower.rs
@@ -134,7 +134,7 @@ impl ExprCollector<'_> {
         self.make_expr(expr, Err(SyntheticSyntax))
     }
     fn empty_block(&mut self) -> ExprId {
-        self.alloc_expr_desugared(Expr::Block { statements: Vec::new(), tail: None })
+        self.alloc_expr_desugared(Expr::Block { statements: Vec::new(), tail: None, label: None })
     }
     fn missing_expr(&mut self) -> ExprId {
         self.alloc_expr_desugared(Expr::Missing)
@@ -215,7 +215,16 @@ impl ExprCollector<'_> {
             ast::Expr::BlockExpr(e) => self.collect_block(e),
             ast::Expr::LoopExpr(e) => {
                 let body = self.collect_block_opt(e.loop_body());
-                self.alloc_expr(Expr::Loop { body }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::Loop {
+                        body,
+                        label: e
+                            .label()
+                            .and_then(|l| l.lifetime_token())
+                            .map(|l| Name::new_lifetime(&l)),
+                    },
+                    syntax_ptr,
+                )
             }
             ast::Expr::WhileExpr(e) => {
                 let body = self.collect_block_opt(e.loop_body());
@@ -230,25 +239,56 @@ impl ExprCollector<'_> {
                             let pat = self.collect_pat(pat);
                             let match_expr = self.collect_expr_opt(condition.expr());
                             let placeholder_pat = self.missing_pat();
-                            let break_ = self.alloc_expr_desugared(Expr::Break { expr: None });
+                            let break_ =
+                                self.alloc_expr_desugared(Expr::Break { expr: None, label: None });
                             let arms = vec![
                                 MatchArm { pat, expr: body, guard: None },
                                 MatchArm { pat: placeholder_pat, expr: break_, guard: None },
                             ];
                             let match_expr =
                                 self.alloc_expr_desugared(Expr::Match { expr: match_expr, arms });
-                            return self.alloc_expr(Expr::Loop { body: match_expr }, syntax_ptr);
+                            return self.alloc_expr(
+                                Expr::Loop {
+                                    body: match_expr,
+                                    label: e
+                                        .label()
+                                        .and_then(|l| l.lifetime_token())
+                                        .map(|l| Name::new_lifetime(&l)),
+                                },
+                                syntax_ptr,
+                            );
                         }
                     },
                 };
 
-                self.alloc_expr(Expr::While { condition, body }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::While {
+                        condition,
+                        body,
+                        label: e
+                            .label()
+                            .and_then(|l| l.lifetime_token())
+                            .map(|l| Name::new_lifetime(&l)),
+                    },
+                    syntax_ptr,
+                )
             }
             ast::Expr::ForExpr(e) => {
                 let iterable = self.collect_expr_opt(e.iterable());
                 let pat = self.collect_pat_opt(e.pat());
                 let body = self.collect_block_opt(e.loop_body());
-                self.alloc_expr(Expr::For { iterable, pat, body }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::For {
+                        iterable,
+                        pat,
+                        body,
+                        label: e
+                            .label()
+                            .and_then(|l| l.lifetime_token())
+                            .map(|l| Name::new_lifetime(&l)),
+                    },
+                    syntax_ptr,
+                )
             }
             ast::Expr::CallExpr(e) => {
                 let callee = self.collect_expr_opt(e.expr());
@@ -301,13 +341,16 @@ impl ExprCollector<'_> {
                     .unwrap_or(Expr::Missing);
                 self.alloc_expr(path, syntax_ptr)
             }
-            ast::Expr::ContinueExpr(_e) => {
-                // FIXME: labels
-                self.alloc_expr(Expr::Continue, syntax_ptr)
-            }
+            ast::Expr::ContinueExpr(e) => self.alloc_expr(
+                Expr::Continue { label: e.lifetime_token().map(|l| Name::new_lifetime(&l)) },
+                syntax_ptr,
+            ),
             ast::Expr::BreakExpr(e) => {
                 let expr = e.expr().map(|e| self.collect_expr(e));
-                self.alloc_expr(Expr::Break { expr }, syntax_ptr)
+                self.alloc_expr(
+                    Expr::Break { expr, label: e.lifetime_token().map(|l| Name::new_lifetime(&l)) },
+                    syntax_ptr,
+                )
             }
             ast::Expr::ParenExpr(e) => {
                 let inner = self.collect_expr_opt(e.expr());
@@ -529,7 +572,8 @@ impl ExprCollector<'_> {
             })
             .collect();
         let tail = block.expr().map(|e| self.collect_expr(e));
-        self.alloc_expr(Expr::Block { statements, tail }, syntax_node_ptr)
+        let label = block.label().and_then(|l| l.lifetime_token()).map(|t| Name::new_lifetime(&t));
+        self.alloc_expr(Expr::Block { statements, tail, label }, syntax_node_ptr)
     }
 
     fn collect_block_items(&mut self, block: &ast::BlockExpr) {
diff --git a/crates/ra_hir_def/src/body/scope.rs b/crates/ra_hir_def/src/body/scope.rs
index 09e92b74e..e48ff38f9 100644
--- a/crates/ra_hir_def/src/body/scope.rs
+++ b/crates/ra_hir_def/src/body/scope.rs
@@ -138,10 +138,10 @@ fn compute_block_scopes(
 fn compute_expr_scopes(expr: ExprId, body: &Body, scopes: &mut ExprScopes, scope: ScopeId) {
     scopes.set_scope(expr, scope);
     match &body[expr] {
-        Expr::Block { statements, tail } => {
+        Expr::Block { statements, tail, .. } => {
             compute_block_scopes(&statements, *tail, body, scopes, scope);
         }
-        Expr::For { iterable, pat, body: body_expr } => {
+        Expr::For { iterable, pat, body: body_expr, .. } => {
             compute_expr_scopes(*iterable, body, scopes, scope);
             let scope = scopes.new_scope(scope);
             scopes.add_bindings(body, scope, *pat);
diff --git a/crates/ra_hir_def/src/data.rs b/crates/ra_hir_def/src/data.rs
index e2130d931..807195d25 100644
--- a/crates/ra_hir_def/src/data.rs
+++ b/crates/ra_hir_def/src/data.rs
@@ -34,6 +34,7 @@ pub struct FunctionData {
     /// True if the first param is `self`. This is relevant to decide whether this
     /// can be called as a method.
     pub has_self_param: bool,
+    pub is_unsafe: bool,
     pub visibility: RawVisibility,
 }
 
@@ -85,11 +86,14 @@ impl FunctionData {
             ret_type
         };
 
+        let is_unsafe = src.value.unsafe_token().is_some();
+
         let vis_default = RawVisibility::default_for_container(loc.container);
         let visibility =
             RawVisibility::from_ast_with_default(db, vis_default, src.map(|s| s.visibility()));
 
-        let sig = FunctionData { name, params, ret_type, has_self_param, visibility, attrs };
+        let sig =
+            FunctionData { name, params, ret_type, has_self_param, is_unsafe, visibility, attrs };
         Arc::new(sig)
     }
 }
diff --git a/crates/ra_hir_def/src/expr.rs b/crates/ra_hir_def/src/expr.rs
index f25c6f958..ca49b26d1 100644
--- a/crates/ra_hir_def/src/expr.rs
+++ b/crates/ra_hir_def/src/expr.rs
@@ -52,18 +52,22 @@ pub enum Expr {
     Block {
         statements: Vec<Statement>,
         tail: Option<ExprId>,
+        label: Option<Name>,
     },
     Loop {
         body: ExprId,
+        label: Option<Name>,
     },
     While {
         condition: ExprId,
         body: ExprId,
+        label: Option<Name>,
     },
     For {
         iterable: ExprId,
         pat: PatId,
         body: ExprId,
+        label: Option<Name>,
     },
     Call {
         callee: ExprId,
@@ -79,9 +83,12 @@ pub enum Expr {
         expr: ExprId,
         arms: Vec<MatchArm>,
     },
-    Continue,
+    Continue {
+        label: Option<Name>,
+    },
     Break {
         expr: Option<ExprId>,
+        label: Option<Name>,
     },
     Return {
         expr: Option<ExprId>,
@@ -225,7 +232,7 @@ impl Expr {
                     f(*else_branch);
                 }
             }
-            Expr::Block { statements, tail } => {
+            Expr::Block { statements, tail, .. } => {
                 for stmt in statements {
                     match stmt {
                         Statement::Let { initializer, .. } => {
@@ -241,8 +248,8 @@ impl Expr {
                 }
             }
             Expr::TryBlock { body } => f(*body),
-            Expr::Loop { body } => f(*body),
-            Expr::While { condition, body } => {
+            Expr::Loop { body, .. } => f(*body),
+            Expr::While { condition, body, .. } => {
                 f(*condition);
                 f(*body);
             }
@@ -268,8 +275,8 @@ impl Expr {
                     f(arm.expr);
                 }
             }
-            Expr::Continue => {}
-            Expr::Break { expr } | Expr::Return { expr } => {
+            Expr::Continue { .. } => {}
+            Expr::Break { expr, .. } | Expr::Return { expr } => {
                 if let Some(expr) = expr {
                     f(*expr);
                 }
diff --git a/crates/ra_hir_expand/src/name.rs b/crates/ra_hir_expand/src/name.rs
index fecce224e..ea495cb11 100644
--- a/crates/ra_hir_expand/src/name.rs
+++ b/crates/ra_hir_expand/src/name.rs
@@ -37,6 +37,11 @@ impl Name {
         Name(Repr::TupleField(idx))
     }
 
+    pub fn new_lifetime(lt: &ra_syntax::SyntaxToken) -> Name {
+        assert!(lt.kind() == ra_syntax::SyntaxKind::LIFETIME);
+        Name(Repr::Text(lt.text().clone()))
+    }
+
     /// Shortcut to create inline plain text name
     const fn new_inline_ascii(text: &[u8]) -> Name {
         Name::new_text(SmolStr::new_inline_from_ascii(text.len(), text))
diff --git a/crates/ra_hir_ty/Cargo.toml b/crates/ra_hir_ty/Cargo.toml
index 6afed58a1..4b8dcdc07 100644
--- a/crates/ra_hir_ty/Cargo.toml
+++ b/crates/ra_hir_ty/Cargo.toml
@@ -27,8 +27,8 @@ test_utils = { path = "../test_utils" }
 
 scoped-tls = "1"
 
-chalk-solve =   { git = "https://github.com/rust-lang/chalk.git", rev = "5a3b871ca17529ab5aa5787594fabad1634936cb" }
-chalk-ir =      { git = "https://github.com/rust-lang/chalk.git", rev = "5a3b871ca17529ab5aa5787594fabad1634936cb" }
+chalk-solve =   { git = "https://github.com/rust-lang/chalk.git", rev = "329b7f3fdd2431ed6f6778cde53f22374c7d094c" }
+chalk-ir =      { git = "https://github.com/rust-lang/chalk.git", rev = "329b7f3fdd2431ed6f6778cde53f22374c7d094c" }
 
 [dev-dependencies]
 insta = "0.16.0"
diff --git a/crates/ra_hir_ty/src/infer.rs b/crates/ra_hir_ty/src/infer.rs
index 957d6e0b5..dc77e88e5 100644
--- a/crates/ra_hir_ty/src/infer.rs
+++ b/crates/ra_hir_ty/src/infer.rs
@@ -219,6 +219,17 @@ struct InferenceContext<'a> {
 struct BreakableContext {
     pub may_break: bool,
     pub break_ty: Ty,
+    pub label: Option<name::Name>,
+}
+
+fn find_breakable<'c>(
+    ctxs: &'c mut [BreakableContext],
+    label: Option<&name::Name>,
+) -> Option<&'c mut BreakableContext> {
+    match label {
+        Some(_) => ctxs.iter_mut().rev().find(|ctx| ctx.label.as_ref() == label),
+        None => ctxs.last_mut(),
+    }
 }
 
 impl<'a> InferenceContext<'a> {
diff --git a/crates/ra_hir_ty/src/infer/coerce.rs b/crates/ra_hir_ty/src/infer/coerce.rs
index 2ee9adb16..32c7c57cd 100644
--- a/crates/ra_hir_ty/src/infer/coerce.rs
+++ b/crates/ra_hir_ty/src/infer/coerce.rs
@@ -45,9 +45,7 @@ impl<'a> InferenceContext<'a> {
                 self.coerce_merge_branch(&ptr_ty1, &ptr_ty2)
             } else {
                 mark::hit!(coerce_merge_fail_fallback);
-                // For incompatible types, we use the latter one as result
-                // to be better recovery for `if` without `else`.
-                ty2.clone()
+                ty1.clone()
             }
         }
     }
diff --git a/crates/ra_hir_ty/src/infer/expr.rs b/crates/ra_hir_ty/src/infer/expr.rs
index 54bab3476..4a98e2deb 100644
--- a/crates/ra_hir_ty/src/infer/expr.rs
+++ b/crates/ra_hir_ty/src/infer/expr.rs
@@ -22,8 +22,8 @@ use crate::{
 };
 
 use super::{
-    BindingMode, BreakableContext, Diverges, Expectation, InferenceContext, InferenceDiagnostic,
-    TypeMismatch,
+    find_breakable, BindingMode, BreakableContext, Diverges, Expectation, InferenceContext,
+    InferenceDiagnostic, TypeMismatch,
 };
 
 impl<'a> InferenceContext<'a> {
@@ -86,16 +86,20 @@ impl<'a> InferenceContext<'a> {
 
                 self.coerce_merge_branch(&then_ty, &else_ty)
             }
-            Expr::Block { statements, tail } => self.infer_block(statements, *tail, expected),
+            Expr::Block { statements, tail, .. } => {
+                // FIXME: Breakable block inference
+                self.infer_block(statements, *tail, expected)
+            }
             Expr::TryBlock { body } => {
                 let _inner = self.infer_expr(*body, expected);
                 // FIXME should be std::result::Result<{inner}, _>
                 Ty::Unknown
             }
-            Expr::Loop { body } => {
+            Expr::Loop { body, label } => {
                 self.breakables.push(BreakableContext {
                     may_break: false,
                     break_ty: self.table.new_type_var(),
+                    label: label.clone(),
                 });
                 self.infer_expr(*body, &Expectation::has_type(Ty::unit()));
 
@@ -110,8 +114,12 @@ impl<'a> InferenceContext<'a> {
                     Ty::simple(TypeCtor::Never)
                 }
             }
-            Expr::While { condition, body } => {
-                self.breakables.push(BreakableContext { may_break: false, break_ty: Ty::Unknown });
+            Expr::While { condition, body, label } => {
+                self.breakables.push(BreakableContext {
+                    may_break: false,
+                    break_ty: Ty::Unknown,
+                    label: label.clone(),
+                });
                 // while let is desugared to a match loop, so this is always simple while
                 self.infer_expr(*condition, &Expectation::has_type(Ty::simple(TypeCtor::Bool)));
                 self.infer_expr(*body, &Expectation::has_type(Ty::unit()));
@@ -120,10 +128,14 @@ impl<'a> InferenceContext<'a> {
                 self.diverges = Diverges::Maybe;
                 Ty::unit()
             }
-            Expr::For { iterable, body, pat } => {
+            Expr::For { iterable, body, pat, label } => {
                 let iterable_ty = self.infer_expr(*iterable, &Expectation::none());
 
-                self.breakables.push(BreakableContext { may_break: false, break_ty: Ty::Unknown });
+                self.breakables.push(BreakableContext {
+                    may_break: false,
+                    break_ty: Ty::Unknown,
+                    label: label.clone(),
+                });
                 let pat_ty =
                     self.resolve_associated_type(iterable_ty, self.resolve_into_iter_item());
 
@@ -140,13 +152,13 @@ impl<'a> InferenceContext<'a> {
 
                 let mut sig_tys = Vec::new();
 
-                for (arg_pat, arg_type) in args.iter().zip(arg_types.iter()) {
-                    let expected = if let Some(type_ref) = arg_type {
+                // collect explicitly written argument types
+                for arg_type in arg_types.iter() {
+                    let arg_ty = if let Some(type_ref) = arg_type {
                         self.make_ty(type_ref)
                     } else {
-                        Ty::Unknown
+                        self.table.new_type_var()
                     };
-                    let arg_ty = self.infer_pat(*arg_pat, &expected, BindingMode::default());
                     sig_tys.push(arg_ty);
                 }
 
@@ -158,7 +170,7 @@ impl<'a> InferenceContext<'a> {
                 sig_tys.push(ret_ty.clone());
                 let sig_ty = Ty::apply(
                     TypeCtor::FnPtr { num_args: sig_tys.len() as u16 - 1 },
-                    Substs(sig_tys.into()),
+                    Substs(sig_tys.clone().into()),
                 );
                 let closure_ty =
                     Ty::apply_one(TypeCtor::Closure { def: self.owner, expr: tgt_expr }, sig_ty);
@@ -168,6 +180,12 @@ impl<'a> InferenceContext<'a> {
                 // infer the body.
                 self.coerce(&closure_ty, &expected.ty);
 
+                // Now go through the argument patterns
+                for (arg_pat, arg_ty) in args.iter().zip(sig_tys) {
+                    let resolved = self.resolve_ty_as_possible(arg_ty);
+                    self.infer_pat(*arg_pat, &resolved, BindingMode::default());
+                }
+
                 let prev_diverges = mem::replace(&mut self.diverges, Diverges::Maybe);
                 let prev_ret_ty = mem::replace(&mut self.return_ty, ret_ty.clone());
 
@@ -230,23 +248,24 @@ impl<'a> InferenceContext<'a> {
                 let resolver = resolver_for_expr(self.db.upcast(), self.owner, tgt_expr);
                 self.infer_path(&resolver, p, tgt_expr.into()).unwrap_or(Ty::Unknown)
             }
-            Expr::Continue => Ty::simple(TypeCtor::Never),
-            Expr::Break { expr } => {
+            Expr::Continue { .. } => Ty::simple(TypeCtor::Never),
+            Expr::Break { expr, label } => {
                 let val_ty = if let Some(expr) = expr {
                     self.infer_expr(*expr, &Expectation::none())
                 } else {
                     Ty::unit()
                 };
 
-                let last_ty = if let Some(ctxt) = self.breakables.last() {
-                    ctxt.break_ty.clone()
-                } else {
-                    Ty::Unknown
-                };
+                let last_ty =
+                    if let Some(ctxt) = find_breakable(&mut self.breakables, label.as_ref()) {
+                        ctxt.break_ty.clone()
+                    } else {
+                        Ty::Unknown
+                    };
 
                 let merged_type = self.coerce_merge_branch(&last_ty, &val_ty);
 
-                if let Some(ctxt) = self.breakables.last_mut() {
+                if let Some(ctxt) = find_breakable(&mut self.breakables, label.as_ref()) {
                     ctxt.break_ty = merged_type;
                     ctxt.may_break = true;
                 } else {
diff --git a/crates/ra_hir_ty/src/tests/patterns.rs b/crates/ra_hir_ty/src/tests/patterns.rs
index 0c5f972a2..fe62587c0 100644
--- a/crates/ra_hir_ty/src/tests/patterns.rs
+++ b/crates/ra_hir_ty/src/tests/patterns.rs
@@ -520,3 +520,53 @@ fn main() {
         105..107 '()': ()
     ")
 }
+
+#[test]
+fn match_ergonomics_in_closure_params() {
+    assert_snapshot!(
+        infer(r#"
+#[lang = "fn_once"]
+trait FnOnce<Args> {
+    type Output;
+}
+
+fn foo<T, U, F: FnOnce(T) -> U>(t: T, f: F) -> U { loop {} }
+
+fn test() {
+    foo(&(1, "a"), |&(x, y)| x); // normal, no match ergonomics
+    foo(&(1, "a"), |(x, y)| x);
+}
+"#),
+        @r###"
+    94..95 't': T
+    100..101 'f': F
+    111..122 '{ loop {} }': U
+    113..120 'loop {}': !
+    118..120 '{}': ()
+    134..233 '{     ... x); }': ()
+    140..143 'foo': fn foo<&(i32, &str), i32, |&(i32, &str)| -> i32>(&(i32, &str), |&(i32, &str)| -> i32) -> i32
+    140..167 'foo(&(...y)| x)': i32
+    144..153 '&(1, "a")': &(i32, &str)
+    145..153 '(1, "a")': (i32, &str)
+    146..147 '1': i32
+    149..152 '"a"': &str
+    155..166 '|&(x, y)| x': |&(i32, &str)| -> i32
+    156..163 '&(x, y)': &(i32, &str)
+    157..163 '(x, y)': (i32, &str)
+    158..159 'x': i32
+    161..162 'y': &str
+    165..166 'x': i32
+    204..207 'foo': fn foo<&(i32, &str), &i32, |&(i32, &str)| -> &i32>(&(i32, &str), |&(i32, &str)| -> &i32) -> &i32
+    204..230 'foo(&(...y)| x)': &i32
+    208..217 '&(1, "a")': &(i32, &str)
+    209..217 '(1, "a")': (i32, &str)
+    210..211 '1': i32
+    213..216 '"a"': &str
+    219..229 '|(x, y)| x': |&(i32, &str)| -> &i32
+    220..226 '(x, y)': (i32, &str)
+    221..222 'x': &i32
+    224..225 'y': &&str
+    228..229 'x': &i32
+    "###
+    );
+}
diff --git a/crates/ra_hir_ty/src/tests/simple.rs b/crates/ra_hir_ty/src/tests/simple.rs
index f1db34160..88309157b 100644
--- a/crates/ra_hir_ty/src/tests/simple.rs
+++ b/crates/ra_hir_ty/src/tests/simple.rs
@@ -957,7 +957,7 @@ fn main(foo: Foo) {
     51..107 'if tru...     }': ()
     54..58 'true': bool
     59..67 '{      }': ()
-    73..107 'if fal...     }': ()
+    73..107 'if fal...     }': i32
     76..81 'false': bool
     82..107 '{     ...     }': i32
     92..95 'foo': Foo
@@ -1943,3 +1943,57 @@ fn test() {
     "###
     );
 }
+
+#[test]
+fn infer_labelled_break_with_val() {
+    assert_snapshot!(
+        infer(r#"
+fn foo() {
+    let _x = || 'outer: loop {
+        let inner = 'inner: loop {
+            let i = Default::default();
+            if (break 'outer i) {
+                loop { break 'inner 5i8; };
+            } else if true {
+                break 'inner 6;
+            }
+            break 7;
+        };
+        break inner < 8;
+    };
+}
+"#),
+        @r###"
+    10..336 '{     ...  }; }': ()
+    20..22 '_x': || -> bool
+    25..333 '|| 'ou...     }': || -> bool
+    28..333 ''outer...     }': bool
+    41..333 '{     ...     }': ()
+    55..60 'inner': i8
+    63..301 ''inner...     }': i8
+    76..301 '{     ...     }': ()
+    94..95 'i': bool
+    98..114 'Defaul...efault': {unknown}
+    98..116 'Defaul...ault()': bool
+    130..270 'if (br...     }': ()
+    134..148 'break 'outer i': !
+    147..148 'i': bool
+    150..209 '{     ...     }': ()
+    168..194 'loop {...5i8; }': !
+    173..194 '{ brea...5i8; }': ()
+    175..191 'break ...er 5i8': !
+    188..191 '5i8': i8
+    215..270 'if tru...     }': ()
+    218..222 'true': bool
+    223..270 '{     ...     }': ()
+    241..255 'break 'inner 6': !
+    254..255 '6': i8
+    283..290 'break 7': !
+    289..290 '7': i8
+    311..326 'break inner < 8': !
+    317..322 'inner': i8
+    317..326 'inner < 8': bool
+    325..326 '8': i8
+    "###
+    );
+}
diff --git a/crates/ra_hir_ty/src/tests/traits.rs b/crates/ra_hir_ty/src/tests/traits.rs
index 0419bc751..e8778d419 100644
--- a/crates/ra_hir_ty/src/tests/traits.rs
+++ b/crates/ra_hir_ty/src/tests/traits.rs
@@ -2665,7 +2665,6 @@ fn test() {
     Enum::Variant.test();
 }
 "#, true),
-        // wrong result, because the built-in Copy impl for fn defs doesn't exist in Chalk yet
         @r###"
     42..44 '{}': ()
     61..62 'T': {unknown}
@@ -2674,13 +2673,13 @@ fn test() {
     146..150 'self': &Self
     202..282 '{     ...t(); }': ()
     208..211 'foo': fn foo()
-    208..218 'foo.test()': {unknown}
+    208..218 'foo.test()': bool
     224..227 'bar': fn bar<{unknown}>({unknown}) -> {unknown}
-    224..234 'bar.test()': {unknown}
+    224..234 'bar.test()': bool
     240..246 'Struct': Struct(usize) -> Struct
-    240..253 'Struct.test()': {unknown}
+    240..253 'Struct.test()': bool
     259..272 'Enum::Variant': Variant(usize) -> Enum
-    259..279 'Enum::...test()': {unknown}
+    259..279 'Enum::...test()': bool
     "###
     );
 }
@@ -2754,3 +2753,48 @@ fn test() {
     "###
     );
 }
+
+#[test]
+fn integer_range_iterate() {
+    let t = type_at(
+        r#"
+//- /main.rs crate:main deps:std
+fn test() {
+    for x in 0..100 { x<|>; }
+}
+
+//- /std.rs crate:std
+pub mod ops {
+    pub struct Range<Idx> {
+        pub start: Idx,
+        pub end: Idx,
+    }
+}
+
+pub mod iter {
+    pub trait Iterator {
+        type Item;
+    }
+
+    pub trait IntoIterator {
+        type Item;
+        type IntoIter: Iterator<Item = Self::Item>;
+    }
+
+    impl<T> IntoIterator for T where T: Iterator {
+        type Item = <T as Iterator>::Item;
+        type IntoIter = Self;
+    }
+}
+
+trait Step {}
+impl Step for i32 {}
+impl Step for i64 {}
+
+impl<A: Step> iter::Iterator for ops::Range<A> {
+    type Item = A;
+}
+"#,
+    );
+    assert_eq!(t, "i32");
+}
diff --git a/crates/ra_ide/src/completion.rs b/crates/ra_ide/src/completion.rs
index 191300704..d890b69d2 100644
--- a/crates/ra_ide/src/completion.rs
+++ b/crates/ra_ide/src/completion.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 mod completion_config;
 mod completion_item;
 mod completion_context;
@@ -35,6 +33,51 @@ pub use crate::completion::{
     completion_item::{CompletionItem, CompletionItemKind, CompletionScore, InsertTextFormat},
 };
 
+//FIXME: split the following feature into fine-grained features.
+
+// Feature: Magic Completions
+//
+// In addition to usual reference completion, rust-analyzer provides some ✨magic✨
+// completions as well:
+//
+// Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
+// is placed at the appropriate position. Even though `if` is easy to type, you
+// still want to complete it, to get ` { }` for free! `return` is inserted with a
+// space or `;` depending on the return type of the function.
+//
+// When completing a function call, `()` are automatically inserted. If a function
+// takes arguments, the cursor is positioned inside the parenthesis.
+//
+// There are postfix completions, which can be triggered by typing something like
+// `foo().if`. The word after `.` determines postfix completion. Possible variants are:
+//
+// - `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
+// - `expr.match` -> `match expr {}`
+// - `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
+// - `expr.ref` -> `&expr`
+// - `expr.refm` -> `&mut expr`
+// - `expr.not` -> `!expr`
+// - `expr.dbg` -> `dbg!(expr)`
+//
+// There also snippet completions:
+//
+// .Expressions
+// - `pd` -> `println!("{:?}")`
+// - `ppd` -> `println!("{:#?}")`
+//
+// .Items
+// - `tfn` -> `#[test] fn f(){}`
+// - `tmod` ->
+// ```rust
+// #[cfg(test)]
+// mod tests {
+//     use super::*;
+//
+//     #[test]
+//     fn test_fn() {}
+// }
+// ```
+
 /// Main entry point for completion. We run completion as a two-phase process.
 ///
 /// First, we look at the position and collect a so-called `CompletionContext.
diff --git a/crates/ra_ide/src/completion/complete_postfix.rs b/crates/ra_ide/src/completion/complete_postfix.rs
index 02e660ca8..59b58bf98 100644
--- a/crates/ra_ide/src/completion/complete_postfix.rs
+++ b/crates/ra_ide/src/completion/complete_postfix.rs
@@ -1,12 +1,11 @@
 //! FIXME: write short doc here
-
+use ra_assists::utils::TryEnum;
 use ra_syntax::{
     ast::{self, AstNode},
     TextRange, TextSize,
 };
 use ra_text_edit::TextEdit;
 
-use super::completion_config::SnippetCap;
 use crate::{
     completion::{
         completion_context::CompletionContext,
@@ -14,7 +13,8 @@ use crate::{
     },
     CompletionItem,
 };
-use ra_assists::utils::TryEnum;
+
+use super::completion_config::SnippetCap;
 
 pub(super) fn complete_postfix(acc: &mut Completions, ctx: &CompletionContext) {
     if !ctx.config.enable_postfix_completions {
diff --git a/crates/ra_ide/src/display/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 3e721dcca..d96cb5596 100644
--- a/crates/ra_ide/src/hover.rs
+++ b/crates/ra_ide/src/hover.rs
@@ -1,10 +1,10 @@
-//! Logic for computing info that is displayed when the user hovers over any
-//! source code items (e.g. function call, struct field, variable symbol...)
+use std::iter::once;
 
 use hir::{
     Adt, AsAssocItem, AssocItemContainer, FieldSource, HasSource, HirDisplay, ModuleDef,
     ModuleSource, Semantics,
 };
+use itertools::Itertools;
 use ra_db::SourceDatabase;
 use ra_ide_db::{
     defs::{classify_name, classify_name_ref, Definition},
@@ -21,8 +21,6 @@ use crate::{
     display::{macro_label, rust_code_markup, rust_code_markup_with_doc, ShortLabel},
     FilePosition, RangeInfo,
 };
-use itertools::Itertools;
-use std::iter::once;
 
 /// Contains the results when hovering over an item
 #[derive(Debug, Default)]
@@ -62,6 +60,63 @@ impl HoverResult {
     }
 }
 
+// Feature: Hover
+//
+// Shows additional information, like type of an expression or documentation for definition when "focusing" code.
+// Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
+pub(crate) fn hover(db: &RootDatabase, position: FilePosition) -> Option<RangeInfo<HoverResult>> {
+    let sema = Semantics::new(db);
+    let file = sema.parse(position.file_id).syntax().clone();
+    let token = pick_best(file.token_at_offset(position.offset))?;
+    let token = sema.descend_into_macros(token);
+
+    let mut res = HoverResult::new();
+
+    if let Some((node, name_kind)) = match_ast! {
+        match (token.parent()) {
+            ast::NameRef(name_ref) => {
+                classify_name_ref(&sema, &name_ref).map(|d| (name_ref.syntax().clone(), d.definition()))
+            },
+            ast::Name(name) => {
+                classify_name(&sema, &name).map(|d| (name.syntax().clone(), d.definition()))
+            },
+            _ => None,
+        }
+    } {
+        let range = sema.original_range(&node).range;
+        res.extend(hover_text_from_name_kind(db, name_kind));
+
+        if !res.is_empty() {
+            return Some(RangeInfo::new(range, res));
+        }
+    }
+
+    let node = token
+        .ancestors()
+        .find(|n| ast::Expr::cast(n.clone()).is_some() || ast::Pat::cast(n.clone()).is_some())?;
+
+    let ty = match_ast! {
+        match node {
+            ast::MacroCall(_it) => {
+                // If this node is a MACRO_CALL, it means that `descend_into_macros` failed to resolve.
+                // (e.g expanding a builtin macro). So we give up here.
+                return None;
+            },
+            ast::Expr(it) => {
+                sema.type_of_expr(&it)
+            },
+            ast::Pat(it) => {
+                sema.type_of_pat(&it)
+            },
+            _ => None,
+        }
+    }?;
+
+    res.extend(Some(rust_code_markup(&ty.display(db))));
+    let range = sema.original_range(&node).range;
+    Some(RangeInfo::new(range, res))
+}
+
 fn hover_text(
     docs: Option<String>,
     desc: Option<String>,
@@ -160,59 +215,6 @@ fn hover_text_from_name_kind(db: &RootDatabase, def: Definition) -> Option<Strin
     }
 }
 
-pub(crate) fn hover(db: &RootDatabase, position: FilePosition) -> Option<RangeInfo<HoverResult>> {
-    let sema = Semantics::new(db);
-    let file = sema.parse(position.file_id).syntax().clone();
-    let token = pick_best(file.token_at_offset(position.offset))?;
-    let token = sema.descend_into_macros(token);
-
-    let mut res = HoverResult::new();
-
-    if let Some((node, name_kind)) = match_ast! {
-        match (token.parent()) {
-            ast::NameRef(name_ref) => {
-                classify_name_ref(&sema, &name_ref).map(|d| (name_ref.syntax().clone(), d.definition()))
-            },
-            ast::Name(name) => {
-                classify_name(&sema, &name).map(|d| (name.syntax().clone(), d.definition()))
-            },
-            _ => None,
-        }
-    } {
-        let range = sema.original_range(&node).range;
-        res.extend(hover_text_from_name_kind(db, name_kind));
-
-        if !res.is_empty() {
-            return Some(RangeInfo::new(range, res));
-        }
-    }
-
-    let node = token
-        .ancestors()
-        .find(|n| ast::Expr::cast(n.clone()).is_some() || ast::Pat::cast(n.clone()).is_some())?;
-
-    let ty = match_ast! {
-        match node {
-            ast::MacroCall(_it) => {
-                // If this node is a MACRO_CALL, it means that `descend_into_macros` failed to resolve.
-                // (e.g expanding a builtin macro). So we give up here.
-                return None;
-            },
-            ast::Expr(it) => {
-                sema.type_of_expr(&it)
-            },
-            ast::Pat(it) => {
-                sema.type_of_pat(&it)
-            },
-            _ => None,
-        }
-    }?;
-
-    res.extend(Some(rust_code_markup(&ty.display(db))));
-    let range = sema.original_range(&node).range;
-    Some(RangeInfo::new(range, res))
-}
-
 fn pick_best(tokens: TokenAtOffset<SyntaxToken>) -> Option<SyntaxToken> {
     return tokens.max_by_key(priority);
     fn priority(n: &SyntaxToken) -> usize {
diff --git a/crates/ra_ide/src/inlay_hints.rs b/crates/ra_ide/src/inlay_hints.rs
index b391f903a..75bd3c96b 100644
--- a/crates/ra_ide/src/inlay_hints.rs
+++ b/crates/ra_ide/src/inlay_hints.rs
@@ -1,5 +1,3 @@
-//! This module defines multiple types of inlay hints and their visibility
-
 use hir::{Adt, HirDisplay, Semantics, Type};
 use ra_ide_db::RootDatabase;
 use ra_prof::profile;
@@ -39,6 +37,26 @@ pub struct InlayHint {
     pub label: SmolStr,
 }
 
+// Feature: Inlay Hints
+//
+// rust-analyzer shows additional information inline with the source code.
+// Editors usually render this using read-only virtual text snippets interspersed with code.
+//
+// rust-analyzer shows hits for
+//
+// * types of local variables
+// * names of function arguments
+// * types of chained expressions
+//
+// **Note:** VS Code does not have native support for inlay hints https://github.com/microsoft/vscode/issues/16221[yet] and the hints are implemented using decorations.
+// This approach has limitations, the caret movement and bracket highlighting near the edges of the hint may be weird:
+// https://github.com/rust-analyzer/rust-analyzer/issues/1623[1], https://github.com/rust-analyzer/rust-analyzer/issues/3453[2].
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Toggle inlay hints*
+// |===
 pub(crate) fn inlay_hints(
     db: &RootDatabase,
     file_id: FileId,
diff --git a/crates/ra_ide/src/join_lines.rs b/crates/ra_ide/src/join_lines.rs
index af1ade8a1..5036c1fb0 100644
--- a/crates/ra_ide/src/join_lines.rs
+++ b/crates/ra_ide/src/join_lines.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use itertools::Itertools;
 use ra_fmt::{compute_ws, extract_trivial_expression};
 use ra_syntax::{
@@ -11,6 +9,15 @@ use ra_syntax::{
 };
 use ra_text_edit::{TextEdit, TextEditBuilder};
 
+// Feature: Join Lines
+//
+// Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Join lines**
+// |===
 pub fn join_lines(file: &SourceFile, range: TextRange) -> TextEdit {
     let range = if range.is_empty() {
         let syntax = file.syntax();
diff --git a/crates/ra_ide/src/lib.rs b/crates/ra_ide/src/lib.rs
index d983cd910..12d5716e8 100644
--- a/crates/ra_ide/src/lib.rs
+++ b/crates/ra_ide/src/lib.rs
@@ -23,6 +23,7 @@ mod completion;
 mod runnables;
 mod goto_definition;
 mod goto_type_definition;
+mod goto_implementation;
 mod extend_selection;
 mod hover;
 mod call_hierarchy;
@@ -30,7 +31,6 @@ mod call_info;
 mod syntax_highlighting;
 mod parent_module;
 mod references;
-mod impls;
 mod diagnostics;
 mod syntax_tree;
 mod folding_ranges;
@@ -373,7 +373,7 @@ impl Analysis {
         &self,
         position: FilePosition,
     ) -> Cancelable<Option<RangeInfo<Vec<NavigationTarget>>>> {
-        self.with_db(|db| impls::goto_implementation(db, position))
+        self.with_db(|db| goto_implementation::goto_implementation(db, position))
     }
 
     /// Returns the type definitions for the symbol at `position`.
diff --git a/crates/ra_ide/src/matching_brace.rs b/crates/ra_ide/src/matching_brace.rs
index b85348706..407a9636d 100644
--- a/crates/ra_ide/src/matching_brace.rs
+++ b/crates/ra_ide/src/matching_brace.rs
@@ -1,7 +1,16 @@
-//! FIXME: write short doc here
-
 use ra_syntax::{ast::AstNode, SourceFile, SyntaxKind, TextSize, T};
 
+// Feature: Matching Brace
+//
+// If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
+// moves cursor to the matching brace. It uses the actual parser to determine
+// braces, so it won't confuse generics with comparisons.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Find matching brace**
+// |===
 pub fn matching_brace(file: &SourceFile, offset: TextSize) -> Option<TextSize> {
     const BRACES: &[SyntaxKind] =
         &[T!['{'], T!['}'], T!['['], T![']'], T!['('], T![')'], T![<], T![>]];
diff --git a/crates/ra_ide/src/parent_module.rs b/crates/ra_ide/src/parent_module.rs
index a083fb1eb..fa1535da5 100644
--- a/crates/ra_ide/src/parent_module.rs
+++ b/crates/ra_ide/src/parent_module.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::Semantics;
 use ra_db::{CrateId, FileId, FilePosition};
 use ra_ide_db::RootDatabase;
@@ -11,6 +9,16 @@ use test_utils::mark;
 
 use crate::NavigationTarget;
 
+// Feature: Parent Module
+//
+// Navigates to the parent module of the current module.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Locate parent module**
+// |===
+
 /// This returns `Vec` because a module may be included from several places. We
 /// don't handle this case yet though, so the Vec has length at most one.
 pub(crate) fn parent_module(db: &RootDatabase, position: FilePosition) -> Vec<NavigationTarget> {
diff --git a/crates/ra_ide/src/references.rs b/crates/ra_ide/src/references.rs
index 96444bf6a..bb40d2043 100644
--- a/crates/ra_ide/src/references.rs
+++ b/crates/ra_ide/src/references.rs
@@ -615,6 +615,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_find_all_refs_nested_module() {
+        let code = r#"
+            //- /lib.rs
+            mod foo {
+                mod bar;
+            }
+
+            fn f<|>() {}
+
+            //- /foo/bar.rs
+            use crate::f;
+
+            fn g() {
+                f();
+            }
+        "#;
+
+        let (analysis, pos) = analysis_and_position(code);
+        let refs = analysis.find_all_refs(pos, None).unwrap().unwrap();
+        check_result(
+            refs,
+            "f FN_DEF FileId(1) 25..34 28..29 Other",
+            &["FileId(2) 11..12 Other", "FileId(2) 27..28 StructLiteral"],
+        );
+    }
+
     fn get_all_refs(text: &str) -> ReferenceSearchResult {
         let (analysis, position) = single_file_with_position(text);
         analysis.find_all_refs(position, None).unwrap().unwrap()
diff --git a/crates/ra_ide/src/runnables.rs b/crates/ra_ide/src/runnables.rs
index 6e7e47199..f32ce0d22 100644
--- a/crates/ra_ide/src/runnables.rs
+++ b/crates/ra_ide/src/runnables.rs
@@ -1,21 +1,19 @@
-//! FIXME: write short doc here
+use std::fmt;
 
 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 ra_cfg::CfgExpr;
-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>,
 }
@@ -26,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),
@@ -44,6 +42,17 @@ pub enum RunnableKind {
     Bin,
 }
 
+// Feature: Run
+//
+// Shows a popup suggesting to run a test/benchmark/binary **at the current cursor
+// location**. Super useful for repeatedly running just a single test. Do bind this
+// to a shortcut!
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Run**
+// |===
 pub(crate) fn runnables(db: &RootDatabase, file_id: FileId) -> Vec<Runnable> {
     let sema = Semantics::new(db);
     let source_file = sema.parse(file_id);
@@ -122,7 +131,8 @@ fn runnable_fn(
     let cfg_exprs =
         attrs.by_key("cfg").tt_values().map(|subtree| ra_cfg::parse_cfg(subtree)).collect();
 
-    Some(Runnable { range: fn_def.syntax().text_range(), kind, cfg_exprs })
+    let nav = NavigationTarget::from_named(sema.db, InFile::new(file_id.into(), &fn_def));
+    Some(Runnable { nav, kind, cfg_exprs })
 }
 
 #[derive(Debug)]
@@ -174,7 +184,6 @@ fn runnable_mod(
     if !has_test_function {
         return None;
     }
-    let range = module.syntax().text_range();
     let module_def = sema.to_def(&module)?;
 
     let path = module_def
@@ -188,7 +197,8 @@ fn runnable_mod(
     let cfg_exprs =
         attrs.by_key("cfg").tt_values().map(|subtree| ra_cfg::parse_cfg(subtree)).collect();
 
-    Some(Runnable { range, kind: RunnableKind::TestMod { path }, cfg_exprs })
+    let nav = module_def.to_nav(sema.db);
+    Some(Runnable { nav, kind: RunnableKind::TestMod { path }, cfg_exprs })
 }
 
 #[cfg(test)]
@@ -218,12 +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",
@@ -235,7 +271,20 @@ mod tests {
                 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",
@@ -270,12 +319,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..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",
@@ -310,12 +385,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: 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",
@@ -345,14 +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",
@@ -387,14 +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",
@@ -431,14 +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",
@@ -470,7 +649,20 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 1..58,
+                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",
@@ -507,7 +699,20 @@ mod tests {
         @r###"
         [
             Runnable {
-                range: 1..80,
+                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",
diff --git a/crates/ra_ide/src/snapshots/highlight_injection.html b/crates/ra_ide/src/snapshots/highlight_injection.html
index 68fc589bc..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; }
diff --git a/crates/ra_ide/src/snapshots/highlight_strings.html b/crates/ra_ide/src/snapshots/highlight_strings.html
index 326744361..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; }
@@ -52,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 352e35095..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; }
diff --git a/crates/ra_ide/src/snapshots/rainbow_highlighting.html b/crates/ra_ide/src/snapshots/rainbow_highlighting.html
index 2a0294f71..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; }
diff --git a/crates/ra_ide/src/ssr.rs b/crates/ra_ide/src/ssr.rs
index 130d3b4c3..93e9aee1d 100644
--- a/crates/ra_ide/src/ssr.rs
+++ b/crates/ra_ide/src/ssr.rs
@@ -1,5 +1,3 @@
-//!  structural search replace
-
 use std::{collections::HashMap, iter::once, str::FromStr};
 
 use ra_db::{SourceDatabase, SourceDatabaseExt};
@@ -25,6 +23,28 @@ impl std::fmt::Display for SsrError {
 
 impl std::error::Error for SsrError {}
 
+// Feature: Structural Seach and Replace
+//
+// Search and replace with named wildcards that will match any expression.
+// The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`.
+// A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement.
+// Available via the command `rust-analyzer.ssr`.
+//
+// ```rust
+// // Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
+//
+// // BEFORE
+// String::from(foo(y + 5, z))
+//
+// // AFTER
+// String::from((y + 5).foo(z))
+// ```
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Structural Search Replace**
+// |===
 pub fn parse_search_replace(
     query: &str,
     parse_only: bool,
diff --git a/crates/ra_ide/src/status.rs b/crates/ra_ide/src/status.rs
index 30eb5c995..5b7992920 100644
--- a/crates/ra_ide/src/status.rs
+++ b/crates/ra_ide/src/status.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use std::{fmt, iter::FromIterator, sync::Arc};
 
 use hir::MacroFile;
@@ -26,6 +24,15 @@ fn macro_syntax_tree_stats(db: &RootDatabase) -> SyntaxTreeStats {
     db.query(hir::db::ParseMacroQuery).entries::<SyntaxTreeStats>()
 }
 
+// Feature: Status
+//
+// Shows internal statistic about memory usage of rust-analyzer.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Status**
+// |===
 pub(crate) fn status(db: &RootDatabase) -> String {
     let files_stats = db.query(FileTextQuery).entries::<FilesStats>();
     let syntax_tree_stats = syntax_tree_stats(db);
diff --git a/crates/ra_ide/src/syntax_highlighting.rs b/crates/ra_ide/src/syntax_highlighting.rs
index 8a995d779..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
@@ -391,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()) {
@@ -398,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);
@@ -450,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,
diff --git a/crates/ra_ide/src/syntax_highlighting/html.rs b/crates/ra_ide/src/syntax_highlighting/html.rs
index edfe61f39..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; }
diff --git a/crates/ra_ide/src/syntax_highlighting/tags.rs b/crates/ra_ide/src/syntax_highlighting/tags.rs
index 46c718c91..94f466966 100644
--- a/crates/ra_ide/src/syntax_highlighting/tags.rs
+++ b/crates/ra_ide/src/syntax_highlighting/tags.rs
@@ -24,12 +24,14 @@ pub enum HighlightTag {
     Enum,
     EnumVariant,
     Field,
+    FormatSpecifier,
     Function,
     Keyword,
     Lifetime,
     Macro,
     Module,
     NumericLiteral,
+    Operator,
     SelfKeyword,
     SelfType,
     Static,
@@ -41,7 +43,6 @@ pub enum HighlightTag {
     Union,
     Local,
     UnresolvedReference,
-    FormatSpecifier,
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
@@ -71,12 +72,14 @@ 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",
@@ -88,7 +91,6 @@ impl HighlightTag {
             HighlightTag::Union => "union",
             HighlightTag::Local => "variable",
             HighlightTag::UnresolvedReference => "unresolved_reference",
-            HighlightTag::FormatSpecifier => "format_specifier",
         }
     }
 }
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 = ".=>";