15 files changed, 518 insertions, 183 deletions

diff --git a/Cargo.lock b/Cargo.lock
index 382eb92e4..6f8a4431d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -126,9 +126,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 [[package]]
 name = "chalk-engine"
 version = "0.9.0"
-source = "git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9#13303bb0067c6ed0572322080ae367ee38f9e7c9"
+source = "git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae#1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae"
 dependencies = [
- "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
+ "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
  "rustc-hash 1.0.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "stacker 0.1.6 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -136,17 +136,17 @@ dependencies = [
 [[package]]
 name = "chalk-ir"
 version = "0.1.0"
-source = "git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9#13303bb0067c6ed0572322080ae367ee38f9e7c9"
+source = "git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae#1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae"
 dependencies = [
- "chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
+ "chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
  "lalrpop-intern 0.15.1 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
 [[package]]
 name = "chalk-macros"
 version = "0.1.1"
-source = "git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9#13303bb0067c6ed0572322080ae367ee38f9e7c9"
+source = "git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae#1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae"
 dependencies = [
  "lazy_static 1.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
@@ -154,22 +154,22 @@ dependencies = [
 [[package]]
 name = "chalk-rust-ir"
 version = "0.1.0"
-source = "git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9#13303bb0067c6ed0572322080ae367ee38f9e7c9"
+source = "git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae#1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae"
 dependencies = [
- "chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
+ "chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
 ]
 
 [[package]]
 name = "chalk-solve"
 version = "0.1.0"
-source = "git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9#13303bb0067c6ed0572322080ae367ee38f9e7c9"
+source = "git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae#1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae"
 dependencies = [
- "chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-rust-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
+ "chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-rust-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
  "ena 0.13.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "itertools 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "petgraph 0.4.13 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -979,9 +979,9 @@ name = "ra_hir"
 version = "0.1.0"
 dependencies = [
  "arrayvec 0.5.1 (registry+https://github.com/rust-lang/crates.io-index)",
- "chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-rust-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
- "chalk-solve 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)",
+ "chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-rust-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
+ "chalk-solve 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)",
  "ena 0.13.1 (registry+https://github.com/rust-lang/crates.io-index)",
  "insta 0.12.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "lalrpop-intern 0.15.1 (registry+https://github.com/rust-lang/crates.io-index)",
@@ -1794,11 +1794,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 "checksum cargo_metadata 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)" = "8d2d1617e838936c0d2323a65cc151e03ae19a7678dd24f72bccf27119b90a5d"
 "checksum cc 1.0.46 (registry+https://github.com/rust-lang/crates.io-index)" = "0213d356d3c4ea2c18c40b037c3be23cd639825c18f25ee670ac7813beeef99c"
 "checksum cfg-if 0.1.10 (registry+https://github.com/rust-lang/crates.io-index)" = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822"
-"checksum chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)" = "<none>"
-"checksum chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)" = "<none>"
-"checksum chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)" = "<none>"
-"checksum chalk-rust-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)" = "<none>"
-"checksum chalk-solve 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=13303bb0067c6ed0572322080ae367ee38f9e7c9)" = "<none>"
+"checksum chalk-engine 0.9.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)" = "<none>"
+"checksum chalk-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)" = "<none>"
+"checksum chalk-macros 0.1.1 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)" = "<none>"
+"checksum chalk-rust-ir 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)" = "<none>"
+"checksum chalk-solve 0.1.0 (git+https://github.com/rust-lang/chalk.git?rev=1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae)" = "<none>"
 "checksum chrono 0.4.9 (registry+https://github.com/rust-lang/crates.io-index)" = "e8493056968583b0193c1bb04d6f7684586f3726992d6c573261941a895dbd68"
 "checksum clicolors-control 1.0.1 (registry+https://github.com/rust-lang/crates.io-index)" = "90082ee5dcdd64dc4e9e0d37fbf3ee325419e39c0092191e0393df65518f741e"
 "checksum cloudabi 0.0.3 (registry+https://github.com/rust-lang/crates.io-index)" = "ddfc5b9aa5d4507acaf872de71051dfd0e309860e88966e1051e462a077aac4f"
diff --git a/crates/ra_assists/src/assists/add_derive.rs b/crates/ra_assists/src/assists/add_derive.rs
index 77ecc33c9..d3ba634c4 100644
--- a/crates/ra_assists/src/assists/add_derive.rs
+++ b/crates/ra_assists/src/assists/add_derive.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast::{self, AstNode, AttrsOwner},
@@ -9,6 +7,22 @@ use ra_syntax::{
 
 use crate::{Assist, AssistCtx, AssistId};
 
+// Assist: add_derive
+// Adds a new `#[derive()]` clause to a struct or enum.
+// ```
+// struct Point {
+//     x: u32,
+//     y: u32,<|>
+// }
+// ```
+// ->
+// ```
+// #[derive()]
+// struct Point {
+//     x: u32,
+//     y: u32,
+// }
+// ```
 pub(crate) fn add_derive(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let nominal = ctx.node_at_offset::<ast::NominalDef>()?;
     let node_start = derive_insertion_offset(&nominal)?;
diff --git a/crates/ra_assists/src/assists/add_explicit_type.rs b/crates/ra_assists/src/assists/add_explicit_type.rs
index 8c83dc987..33b7bea7f 100644
--- a/crates/ra_assists/src/assists/add_explicit_type.rs
+++ b/crates/ra_assists/src/assists/add_explicit_type.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::{db::HirDatabase, HirDisplay, Ty};
 use ra_syntax::{
     ast::{self, AstNode, LetStmt, NameOwner},
@@ -8,7 +6,19 @@ use ra_syntax::{
 
 use crate::{Assist, AssistCtx, AssistId};
 
-/// Add explicit type assist.
+// Assist: add_explicit_type
+// Specify type for a let binding
+// ```
+// fn main() {
+//     let x<|> = 92;
+// }
+// ```
+// ->
+// ```
+// fn main() {
+//     let x: i32 = 92;
+// }
+// ```
 pub(crate) fn add_explicit_type(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let stmt = ctx.node_at_offset::<LetStmt>()?;
     let expr = stmt.initializer()?;
diff --git a/crates/ra_assists/src/assists/add_impl.rs b/crates/ra_assists/src/assists/add_impl.rs
index 94801fbc9..40bc5c464 100644
--- a/crates/ra_assists/src/assists/add_impl.rs
+++ b/crates/ra_assists/src/assists/add_impl.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use format_buf::format;
 use hir::db::HirDatabase;
 use join_to_string::join;
@@ -10,6 +8,23 @@ use ra_syntax::{
 
 use crate::{Assist, AssistCtx, AssistId};
 
+// Assist: add_impl
+// Adds a new inherent impl for a type
+// ```
+// struct Ctx<T: Clone> {
+//      data: T,<|>
+// }
+// ```
+// ->
+// ```
+// struct Ctx<T: Clone> {
+//      data: T,
+// }
+//
+// impl<T: Clone> Ctx<T> {
+//
+// }
+// ```
 pub(crate) fn add_impl(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let nominal = ctx.node_at_offset::<ast::NominalDef>()?;
     let name = nominal.name()?;
diff --git a/crates/ra_assists/src/assists/add_missing_impl_members.rs b/crates/ra_assists/src/assists/add_missing_impl_members.rs
index 565b96fb5..36fa6f9ea 100644
--- a/crates/ra_assists/src/assists/add_missing_impl_members.rs
+++ b/crates/ra_assists/src/assists/add_missing_impl_members.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::{db::HirDatabase, HasSource};
 use ra_syntax::{
     ast::{self, edit, make, AstNode, NameOwner},
@@ -14,6 +12,32 @@ enum AddMissingImplMembersMode {
     NoDefaultMethods,
 }
 
+// Assist: add_impl_missing_members
+// Adds scaffold for required impl members
+// ```
+// trait T {
+//     Type X;
+//     fn foo(&self);
+//     fn bar(&self) {}
+// }
+//
+// impl T for () {<|>
+//
+// }
+// ```
+// ->
+// ```
+// trait T {
+//     Type X;
+//     fn foo(&self);
+//     fn bar(&self) {}
+// }
+//
+// impl T for () {
+//     fn foo(&self) { unimplemented!() }
+//
+// }
+// ```
 pub(crate) fn add_missing_impl_members(ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     add_missing_impl_members_inner(
         ctx,
@@ -23,6 +47,36 @@ pub(crate) fn add_missing_impl_members(ctx: AssistCtx<impl HirDatabase>) -> Opti
     )
 }
 
+// Assist: add_impl_default_members
+// Adds scaffold for overriding default impl members
+// ```
+// trait T {
+//     Type X;
+//     fn foo(&self);
+//     fn bar(&self) {}
+// }
+//
+// impl T for () {
+//     Type X = ();
+//     fn foo(&self) {}<|>
+//
+// }
+// ```
+// ->
+// ```
+// trait T {
+//     Type X;
+//     fn foo(&self);
+//     fn bar(&self) {}
+// }
+//
+// impl T for () {
+//     Type X = ();
+//     fn foo(&self) {}
+//     fn bar(&self) {}
+//
+// }
+// ```
 pub(crate) fn add_missing_default_members(ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     add_missing_impl_members_inner(
         ctx,
diff --git a/crates/ra_assists/src/assists/apply_demorgan.rs b/crates/ra_assists/src/assists/apply_demorgan.rs
index 5f2b0dd18..a072f63e7 100644
--- a/crates/ra_assists/src/assists/apply_demorgan.rs
+++ b/crates/ra_assists/src/assists/apply_demorgan.rs
@@ -1,18 +1,26 @@
-//! This contains the functions associated with the demorgan assist.
-//! This assist transforms boolean expressions of the form `!a || !b` into
-//! `!(a && b)`.
 use hir::db::HirDatabase;
 use ra_syntax::ast::{self, AstNode};
 use ra_syntax::SyntaxNode;
 
 use crate::{Assist, AssistCtx, AssistId};
 
-/// Assist for applying demorgan's law
-///
-/// This transforms expressions of the form `!l || !r` into `!(l && r)`.
-/// This also works with `&&`. This assist can only be applied with the cursor
-/// on either `||` or `&&`, with both operands being a negation of some kind.
-/// This means something of the form `!x` or `x != y`.
+// Assist: apply_demorgan
+// Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
+// This transforms expressions of the form `!l || !r` into `!(l && r)`.
+// This also works with `&&`. This assist can only be applied with the cursor
+// on either `||` or `&&`, with both operands being a negation of some kind.
+// This means something of the form `!x` or `x != y`.
+// ```
+// fn main() {
+//     if x != 4 ||<|> !y {}
+// }
+// ```
+// ->
+// ```
+// fn main() {
+//     if !(x == 4 && y) {}
+// }
+// ```
 pub(crate) fn apply_demorgan(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let expr = ctx.node_at_offset::<ast::BinExpr>()?;
     let op = expr.op_kind()?;
diff --git a/crates/ra_assists/src/doc_tests.rs b/crates/ra_assists/src/doc_tests.rs
index 88e901517..872bbdf17 100644
--- a/crates/ra_assists/src/doc_tests.rs
+++ b/crates/ra_assists/src/doc_tests.rs
@@ -15,8 +15,10 @@ fn check(assist_id: &str, before: &str, after: &str) {
     let (db, _source_root, file_id) = MockDatabase::with_single_file(&before);
     let frange = FileRange { file_id, range: TextRange::offset_len(before_cursor_pos, 0.into()) };
 
-    let (_assist_id, action) =
-        crate::assists(&db, frange).into_iter().find(|(id, _)| id.id.0 == assist_id).unwrap();
+    let (_assist_id, action) = crate::assists(&db, frange)
+        .into_iter()
+        .find(|(id, _)| id.id.0 == assist_id)
+        .unwrap_or_else(|| panic!("Assist {:?} is not applicable", assist_id));
 
     let actual = action.edit.apply(&before);
     assert_eq_text!(after, &actual);
diff --git a/crates/ra_assists/src/doc_tests/generated.rs b/crates/ra_assists/src/doc_tests/generated.rs
index e5f6910f1..76d86b93d 100644
--- a/crates/ra_assists/src/doc_tests/generated.rs
+++ b/crates/ra_assists/src/doc_tests/generated.rs
@@ -3,6 +3,145 @@
 use super::check;
 
 #[test]
+fn doctest_add_derive() {
+    check(
+        "add_derive",
+        r#####"
+struct Point {
+    x: u32,
+    y: u32,<|>
+}
+"#####,
+        r#####"
+#[derive()]
+struct Point {
+    x: u32,
+    y: u32,
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_add_explicit_type() {
+    check(
+        "add_explicit_type",
+        r#####"
+fn main() {
+    let x<|> = 92;
+}
+"#####,
+        r#####"
+fn main() {
+    let x: i32 = 92;
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_add_impl() {
+    check(
+        "add_impl",
+        r#####"
+struct Ctx<T: Clone> {
+     data: T,<|>
+}
+"#####,
+        r#####"
+struct Ctx<T: Clone> {
+     data: T,
+}
+
+impl<T: Clone> Ctx<T> {
+
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_add_impl_default_members() {
+    check(
+        "add_impl_default_members",
+        r#####"
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {
+    Type X = ();
+    fn foo(&self) {}<|>
+
+}
+"#####,
+        r#####"
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {
+    Type X = ();
+    fn foo(&self) {}
+    fn bar(&self) {}
+
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_add_impl_missing_members() {
+    check(
+        "add_impl_missing_members",
+        r#####"
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {<|>
+
+}
+"#####,
+        r#####"
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {
+    fn foo(&self) { unimplemented!() }
+
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_apply_demorgan() {
+    check(
+        "apply_demorgan",
+        r#####"
+fn main() {
+    if x != 4 ||<|> !y {}
+}
+"#####,
+        r#####"
+fn main() {
+    if !(x == 4 && y) {}
+}
+"#####,
+    )
+}
+
+#[test]
 fn doctest_convert_to_guarded_return() {
     check(
         "convert_to_guarded_return",
diff --git a/crates/ra_hir/Cargo.toml b/crates/ra_hir/Cargo.toml
index dce897d30..f05ec0b8a 100644
--- a/crates/ra_hir/Cargo.toml
+++ b/crates/ra_hir/Cargo.toml
@@ -22,9 +22,9 @@ tt = { path = "../ra_tt", package = "ra_tt" }
 test_utils = { path = "../test_utils" }
 ra_prof = { path = "../ra_prof" }
 
-chalk-solve = { git = "https://github.com/rust-lang/chalk.git", rev = "13303bb0067c6ed0572322080ae367ee38f9e7c9" }
-chalk-rust-ir = { git = "https://github.com/rust-lang/chalk.git", rev = "13303bb0067c6ed0572322080ae367ee38f9e7c9" }
-chalk-ir = { git = "https://github.com/rust-lang/chalk.git", rev = "13303bb0067c6ed0572322080ae367ee38f9e7c9" }
+chalk-solve = { git = "https://github.com/rust-lang/chalk.git", rev = "1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae" }
+chalk-rust-ir = { git = "https://github.com/rust-lang/chalk.git", rev = "1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae" }
+chalk-ir = { git = "https://github.com/rust-lang/chalk.git", rev = "1e5c1929364dfbb7c0c7ac0956b8250abe7c2cae" }
 lalrpop-intern = "0.15.1"
 
 [dev-dependencies]
diff --git a/crates/ra_hir/src/ty/traits.rs b/crates/ra_hir/src/ty/traits.rs
index 0cb5c3798..4f1eab150 100644
--- a/crates/ra_hir/src/ty/traits.rs
+++ b/crates/ra_hir/src/ty/traits.rs
@@ -1,7 +1,7 @@
 //! Trait solving using Chalk.
 use std::sync::{Arc, Mutex};
 
-use chalk_ir::cast::Cast;
+use chalk_ir::{cast::Cast, family::ChalkIr};
 use log::debug;
 use ra_db::salsa;
 use ra_prof::profile;
@@ -33,7 +33,7 @@ impl TraitSolver {
     fn solve(
         &self,
         db: &impl HirDatabase,
-        goal: &chalk_ir::UCanonical<chalk_ir::InEnvironment<chalk_ir::Goal>>,
+        goal: &chalk_ir::UCanonical<chalk_ir::InEnvironment<chalk_ir::Goal<ChalkIr>>>,
     ) -> Option<chalk_solve::Solution> {
         let context = ChalkContext { db, krate: self.krate };
         debug!("solve goal: {:?}", goal);
@@ -196,7 +196,7 @@ pub(crate) fn trait_solve_query(
 }
 
 fn solution_from_chalk(db: &impl HirDatabase, solution: chalk_solve::Solution) -> Solution {
-    let convert_subst = |subst: chalk_ir::Canonical<chalk_ir::Substitution>| {
+    let convert_subst = |subst: chalk_ir::Canonical<chalk_ir::Substitution<ChalkIr>>| {
         let value = subst
             .value
             .parameters
diff --git a/crates/ra_hir/src/ty/traits/chalk.rs b/crates/ra_hir/src/ty/traits/chalk.rs
index 00aaf65d9..ad7c11a5a 100644
--- a/crates/ra_hir/src/ty/traits/chalk.rs
+++ b/crates/ra_hir/src/ty/traits/chalk.rs
@@ -4,8 +4,8 @@ use std::sync::Arc;
 use log::debug;
 
 use chalk_ir::{
-    cast::Cast, Identifier, ImplId, Parameter, PlaceholderIndex, TypeId, TypeKindId, TypeName,
-    UniverseIndex,
+    cast::Cast, family::ChalkIr, Identifier, ImplId, Parameter, PlaceholderIndex, TypeId,
+    TypeKindId, TypeName, UniverseIndex,
 };
 use chalk_rust_ir::{AssociatedTyDatum, ImplDatum, StructDatum, TraitDatum};
 
@@ -38,8 +38,8 @@ where
 }
 
 impl ToChalk for Ty {
-    type Chalk = chalk_ir::Ty;
-    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::Ty {
+    type Chalk = chalk_ir::Ty<ChalkIr>;
+    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::Ty<ChalkIr> {
         match self {
             Ty::Apply(apply_ty) => {
                 let name = match apply_ty.ctor {
@@ -62,21 +62,21 @@ impl ToChalk for Ty {
                 chalk_ir::ProjectionTy { associated_ty_id, parameters }.cast()
             }
             Ty::Param { idx, .. } => {
-                PlaceholderIndex { ui: UniverseIndex::ROOT, idx: idx as usize }.to_ty()
+                PlaceholderIndex { ui: UniverseIndex::ROOT, idx: idx as usize }.to_ty::<ChalkIr>()
             }
             Ty::Bound(idx) => chalk_ir::Ty::BoundVar(idx as usize),
             Ty::Infer(_infer_ty) => panic!("uncanonicalized infer ty"),
             // FIXME this is clearly incorrect, but probably not too incorrect
             // and I'm not sure what to actually do with Ty::Unknown
             // maybe an alternative would be `for<T> T`? (meaningless in rust, but expressible in chalk's Ty)
-            //
-            // FIXME also dyn and impl Trait are currently handled like Unknown because Chalk doesn't have them yet
+            // FIXME use Chalk's Dyn/Opaque once the bugs with that are fixed
             Ty::Unknown | Ty::Dyn(_) | Ty::Opaque(_) => {
-                PlaceholderIndex { ui: UniverseIndex::ROOT, idx: usize::max_value() }.to_ty()
+                PlaceholderIndex { ui: UniverseIndex::ROOT, idx: usize::max_value() }
+                    .to_ty::<ChalkIr>()
             }
         }
     }
-    fn from_chalk(db: &impl HirDatabase, chalk: chalk_ir::Ty) -> Self {
+    fn from_chalk(db: &impl HirDatabase, chalk: chalk_ir::Ty<ChalkIr>) -> Self {
         match chalk {
             chalk_ir::Ty::Apply(apply_ty) => {
                 // FIXME this is kind of hacky due to the fact that
@@ -108,18 +108,30 @@ impl ToChalk for Ty {
             chalk_ir::Ty::ForAll(_) => unimplemented!(),
             chalk_ir::Ty::BoundVar(idx) => Ty::Bound(idx as u32),
             chalk_ir::Ty::InferenceVar(_iv) => Ty::Unknown,
+            chalk_ir::Ty::Dyn(where_clauses) => {
+                assert_eq!(where_clauses.binders.len(), 1);
+                let predicates =
+                    where_clauses.value.into_iter().map(|c| from_chalk(db, c)).collect();
+                Ty::Dyn(predicates)
+            }
+            chalk_ir::Ty::Opaque(where_clauses) => {
+                assert_eq!(where_clauses.binders.len(), 1);
+                let predicates =
+                    where_clauses.value.into_iter().map(|c| from_chalk(db, c)).collect();
+                Ty::Opaque(predicates)
+            }
         }
     }
 }
 
 impl ToChalk for Substs {
-    type Chalk = Vec<chalk_ir::Parameter>;
+    type Chalk = Vec<chalk_ir::Parameter<ChalkIr>>;
 
-    fn to_chalk(self, db: &impl HirDatabase) -> Vec<Parameter> {
+    fn to_chalk(self, db: &impl HirDatabase) -> Vec<Parameter<ChalkIr>> {
         self.iter().map(|ty| ty.clone().to_chalk(db).cast()).collect()
     }
 
-    fn from_chalk(db: &impl HirDatabase, parameters: Vec<chalk_ir::Parameter>) -> Substs {
+    fn from_chalk(db: &impl HirDatabase, parameters: Vec<chalk_ir::Parameter<ChalkIr>>) -> Substs {
         let tys = parameters
             .into_iter()
             .map(|p| match p {
@@ -132,15 +144,15 @@ impl ToChalk for Substs {
 }
 
 impl ToChalk for TraitRef {
-    type Chalk = chalk_ir::TraitRef;
+    type Chalk = chalk_ir::TraitRef<ChalkIr>;
 
-    fn to_chalk(self: TraitRef, db: &impl HirDatabase) -> chalk_ir::TraitRef {
+    fn to_chalk(self: TraitRef, db: &impl HirDatabase) -> chalk_ir::TraitRef<ChalkIr> {
         let trait_id = self.trait_.to_chalk(db);
         let parameters = self.substs.to_chalk(db);
         chalk_ir::TraitRef { trait_id, parameters }
     }
 
-    fn from_chalk(db: &impl HirDatabase, trait_ref: chalk_ir::TraitRef) -> Self {
+    fn from_chalk(db: &impl HirDatabase, trait_ref: chalk_ir::TraitRef<ChalkIr>) -> Self {
         let trait_ = from_chalk(db, trait_ref.trait_id);
         let substs = from_chalk(db, trait_ref.parameters);
         TraitRef { trait_, substs }
@@ -196,9 +208,9 @@ impl ToChalk for TypeAlias {
 }
 
 impl ToChalk for GenericPredicate {
-    type Chalk = chalk_ir::QuantifiedWhereClause;
+    type Chalk = chalk_ir::QuantifiedWhereClause<ChalkIr>;
 
-    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::QuantifiedWhereClause {
+    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::QuantifiedWhereClause<ChalkIr> {
         match self {
             GenericPredicate::Implemented(trait_ref) => {
                 make_binders(chalk_ir::WhereClause::Implemented(trait_ref.to_chalk(db)), 0)
@@ -221,25 +233,40 @@ impl ToChalk for GenericPredicate {
     }
 
     fn from_chalk(
-        _db: &impl HirDatabase,
-        _where_clause: chalk_ir::QuantifiedWhereClause,
+        db: &impl HirDatabase,
+        where_clause: chalk_ir::QuantifiedWhereClause<ChalkIr>,
     ) -> GenericPredicate {
-        // This should never need to be called
-        unimplemented!()
+        match where_clause.value {
+            chalk_ir::WhereClause::Implemented(tr) => {
+                if tr.trait_id == UNKNOWN_TRAIT {
+                    // FIXME we need an Error enum on the Chalk side to avoid this
+                    return GenericPredicate::Error;
+                }
+                GenericPredicate::Implemented(from_chalk(db, tr))
+            }
+            chalk_ir::WhereClause::ProjectionEq(projection_eq) => {
+                let projection_ty = from_chalk(db, projection_eq.projection);
+                let ty = from_chalk(db, projection_eq.ty);
+                GenericPredicate::Projection(super::ProjectionPredicate { projection_ty, ty })
+            }
+        }
     }
 }
 
 impl ToChalk for ProjectionTy {
-    type Chalk = chalk_ir::ProjectionTy;
+    type Chalk = chalk_ir::ProjectionTy<ChalkIr>;
 
-    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::ProjectionTy {
+    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::ProjectionTy<ChalkIr> {
         chalk_ir::ProjectionTy {
             associated_ty_id: self.associated_ty.to_chalk(db),
             parameters: self.parameters.to_chalk(db),
         }
     }
 
-    fn from_chalk(db: &impl HirDatabase, projection_ty: chalk_ir::ProjectionTy) -> ProjectionTy {
+    fn from_chalk(
+        db: &impl HirDatabase,
+        projection_ty: chalk_ir::ProjectionTy<ChalkIr>,
+    ) -> ProjectionTy {
         ProjectionTy {
             associated_ty: from_chalk(db, projection_ty.associated_ty_id),
             parameters: from_chalk(db, projection_ty.parameters),
@@ -248,31 +275,31 @@ impl ToChalk for ProjectionTy {
 }
 
 impl ToChalk for super::ProjectionPredicate {
-    type Chalk = chalk_ir::Normalize;
+    type Chalk = chalk_ir::Normalize<ChalkIr>;
 
-    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::Normalize {
+    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::Normalize<ChalkIr> {
         chalk_ir::Normalize {
             projection: self.projection_ty.to_chalk(db),
             ty: self.ty.to_chalk(db),
         }
     }
 
-    fn from_chalk(_db: &impl HirDatabase, _normalize: chalk_ir::Normalize) -> Self {
+    fn from_chalk(_db: &impl HirDatabase, _normalize: chalk_ir::Normalize<ChalkIr>) -> Self {
         unimplemented!()
     }
 }
 
 impl ToChalk for Obligation {
-    type Chalk = chalk_ir::DomainGoal;
+    type Chalk = chalk_ir::DomainGoal<ChalkIr>;
 
-    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::DomainGoal {
+    fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::DomainGoal<ChalkIr> {
         match self {
             Obligation::Trait(tr) => tr.to_chalk(db).cast(),
             Obligation::Projection(pr) => pr.to_chalk(db).cast(),
         }
     }
 
-    fn from_chalk(_db: &impl HirDatabase, _goal: chalk_ir::DomainGoal) -> Self {
+    fn from_chalk(_db: &impl HirDatabase, _goal: chalk_ir::DomainGoal<ChalkIr>) -> Self {
         unimplemented!()
     }
 }
@@ -296,16 +323,16 @@ where
 }
 
 impl ToChalk for Arc<super::TraitEnvironment> {
-    type Chalk = Arc<chalk_ir::Environment>;
+    type Chalk = Arc<chalk_ir::Environment<ChalkIr>>;
 
-    fn to_chalk(self, db: &impl HirDatabase) -> Arc<chalk_ir::Environment> {
+    fn to_chalk(self, db: &impl HirDatabase) -> Arc<chalk_ir::Environment<ChalkIr>> {
         let mut clauses = Vec::new();
         for pred in &self.predicates {
             if pred.is_error() {
                 // for env, we just ignore errors
                 continue;
             }
-            let program_clause: chalk_ir::ProgramClause = pred.clone().to_chalk(db).cast();
+            let program_clause: chalk_ir::ProgramClause<ChalkIr> = pred.clone().to_chalk(db).cast();
             clauses.push(program_clause.into_from_env_clause());
         }
         chalk_ir::Environment::new().add_clauses(clauses)
@@ -313,13 +340,16 @@ impl ToChalk for Arc<super::TraitEnvironment> {
 
     fn from_chalk(
         _db: &impl HirDatabase,
-        _env: Arc<chalk_ir::Environment>,
+        _env: Arc<chalk_ir::Environment<ChalkIr>>,
     ) -> Arc<super::TraitEnvironment> {
         unimplemented!()
     }
 }
 
-impl<T: ToChalk> ToChalk for super::InEnvironment<T> {
+impl<T: ToChalk> ToChalk for super::InEnvironment<T>
+where
+    T::Chalk: chalk_ir::family::HasTypeFamily<TypeFamily = ChalkIr>,
+{
     type Chalk = chalk_ir::InEnvironment<T::Chalk>;
 
     fn to_chalk(self, db: &impl HirDatabase) -> chalk_ir::InEnvironment<T::Chalk> {
@@ -351,7 +381,7 @@ fn convert_where_clauses(
     db: &impl HirDatabase,
     def: GenericDef,
     substs: &Substs,
-) -> Vec<chalk_ir::QuantifiedWhereClause> {
+) -> Vec<chalk_ir::QuantifiedWhereClause<ChalkIr>> {
     let generic_predicates = db.generic_predicates(def);
     let mut result = Vec::with_capacity(generic_predicates.len());
     for pred in generic_predicates.iter() {
@@ -384,7 +414,7 @@ where
     fn impls_for_trait(
         &self,
         trait_id: chalk_ir::TraitId,
-        parameters: &[Parameter],
+        parameters: &[Parameter<ChalkIr>],
     ) -> Vec<ImplId> {
         debug!("impls_for_trait {:?}", trait_id);
         if trait_id == UNKNOWN_TRAIT {
@@ -430,13 +460,13 @@ where
     }
     fn split_projection<'p>(
         &self,
-        projection: &'p chalk_ir::ProjectionTy,
-    ) -> (Arc<AssociatedTyDatum>, &'p [Parameter], &'p [Parameter]) {
+        projection: &'p chalk_ir::ProjectionTy<ChalkIr>,
+    ) -> (Arc<AssociatedTyDatum>, &'p [Parameter<ChalkIr>], &'p [Parameter<ChalkIr>]) {
         debug!("split_projection {:?}", projection);
         // we don't support GATs, so I think this should always be correct currently
         (self.db.associated_ty_data(projection.associated_ty_id), &projection.parameters, &[])
     }
-    fn custom_clauses(&self) -> Vec<chalk_ir::ProgramClause> {
+    fn custom_clauses(&self) -> Vec<chalk_ir::ProgramClause<ChalkIr>> {
         vec![]
     }
     fn local_impls_to_coherence_check(
diff --git a/docs/user/assists.md b/docs/user/assists.md
index cb4b0b9fb..eeb486832 100644
--- a/docs/user/assists.md
+++ b/docs/user/assists.md
@@ -1,5 +1,142 @@
 # Assists
 
+## `add_derive`
+
+Adds a new `#[derive()]` clause to a struct or enum.
+
+```rust
+// BEFORE
+struct Point {
+    x: u32,
+    y: u32,<|>
+}
+
+// AFTER
+#[derive()]
+struct Point {
+    x: u32,
+    y: u32,
+}
+```
+
+## `add_explicit_type`
+
+Specify type for a let binding
+
+```rust
+// BEFORE
+fn main() {
+    let x<|> = 92;
+}
+
+// AFTER
+fn main() {
+    let x: i32 = 92;
+}
+```
+
+## `add_impl`
+
+Adds a new inherent impl for a type
+
+```rust
+// BEFORE
+struct Ctx<T: Clone> {
+     data: T,<|>
+}
+
+// AFTER
+struct Ctx<T: Clone> {
+     data: T,
+}
+
+impl<T: Clone> Ctx<T> {
+
+}
+```
+
+## `add_impl_default_members`
+
+Adds scaffold for overriding default impl members
+
+```rust
+// BEFORE
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {
+    Type X = ();
+    fn foo(&self) {}<|>
+
+}
+
+// AFTER
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {
+    Type X = ();
+    fn foo(&self) {}
+    fn bar(&self) {}
+
+}
+```
+
+## `add_impl_missing_members`
+
+Adds scaffold for required impl members
+
+```rust
+// BEFORE
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {<|>
+
+}
+
+// AFTER
+trait T {
+    Type X;
+    fn foo(&self);
+    fn bar(&self) {}
+}
+
+impl T for () {
+    fn foo(&self) { unimplemented!() }
+
+}
+```
+
+## `apply_demorgan`
+
+Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
+This transforms expressions of the form `!l || !r` into `!(l && r)`.
+This also works with `&&`. This assist can only be applied with the cursor
+on either `||` or `&&`, with both operands being a negation of some kind.
+This means something of the form `!x` or `x != y`.
+
+```rust
+// BEFORE
+fn main() {
+    if x != 4 ||<|> !y {}
+}
+
+// AFTER
+fn main() {
+    if !(x == 4 && y) {}
+}
+```
+
 ## `convert_to_guarded_return`
 
 Replace a large conditional with a guarded return.
diff --git a/docs/user/features.md b/docs/user/features.md
index a94b65ad4..acf092cec 100644
--- a/docs/user/features.md
+++ b/docs/user/features.md
@@ -104,84 +104,6 @@ the VS Code side to be able to position cursor. `<|>` signifies cursor
 
 See [assists.md](./assists.md)
 
-- Add `#[derive]`
-
-```rust
-// before:
-struct Foo {
-    <|>x: i32
-}
-// after:
-#[derive(<|>)]
-struct Foo {
-    x: i32
-}
-```
-
-- Add `impl`
-
-```rust
-// before:
-struct Foo<'a, T: Debug> {
-    <|>t: T
-}
-// after:
-struct Foo<'a, T: Debug> {
-    t: T
-}
-
-impl<'a, T: Debug> Foo<'a, T> {
-    <|>
-}
-```
-
-- Add missing `impl` members
-
-```rust
-// before:
-trait Foo {
-    fn foo(&self);
-    fn bar(&self);
-    fn baz(&self);
-}
-
-struct S;
-
-impl Foo for S {
-    fn bar(&self) {}
-    <|>
-}
-
-// after:
-trait Foo {
-    fn foo(&self);
-    fn bar(&self);
-    fn baz(&self);
-}
-
-struct S;
-
-impl Foo for S {
-    fn bar(&self) {}
-    fn foo(&self) { unimplemented!() }
-    fn baz(&self) { unimplemented!() }<|>
-}
-```
-
-- Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws)
-
-```rust
-// before:
-fn example(x: bool) -> bool {
-    !x || !x
-}
-
-// after:
-fn example(x: bool) -> bool {
-    !(x && x)
-}
-```
-
 - Import path
 
 ```rust
@@ -391,19 +313,6 @@ fn foo() {
 }
 ```
 
-- Add explicit type
-
-```rust
-// before:
-fn foo() {
-    let t<|> = (&2, Some(1));
-}
-// after:
-fn foo() {
-    let t<|>: (&i32, Option<i32>) = (&2, Some(1));
-}
-```
-
 - Move guard expression to match arm body
 ```rust
 // before:
diff --git a/xtask/src/codegen.rs b/xtask/src/codegen.rs
index 44729cd57..4ec8ab75a 100644
--- a/xtask/src/codegen.rs
+++ b/xtask/src/codegen.rs
@@ -74,6 +74,14 @@ fn reformat(text: impl std::fmt::Display) -> Result<String> {
 }
 
 fn extract_comment_blocks(text: &str) -> Vec<Vec<String>> {
+    do_extract_comment_blocks(text, false)
+}
+
+fn extract_comment_blocks_with_empty_lines(text: &str) -> Vec<Vec<String>> {
+    do_extract_comment_blocks(text, true)
+}
+
+fn do_extract_comment_blocks(text: &str, allow_blocks_with_empty_lins: bool) -> Vec<Vec<String>> {
     let mut res = Vec::new();
 
     let prefix = "// ";
@@ -81,6 +89,11 @@ fn extract_comment_blocks(text: &str) -> Vec<Vec<String>> {
 
     let mut block = vec![];
     for line in lines {
+        if line == "//" && allow_blocks_with_empty_lins {
+            block.push(String::new());
+            continue;
+        }
+
         let is_comment = line.starts_with(prefix);
         if is_comment {
             block.push(line[prefix.len()..].to_string());
diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs
index 654ae09d6..e313820d1 100644
--- a/xtask/src/codegen/gen_assists_docs.rs
+++ b/xtask/src/codegen/gen_assists_docs.rs
@@ -1,7 +1,7 @@
 use std::{fs, path::Path};
 
 use crate::{
-    codegen::{self, extract_comment_blocks, Mode},
+    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
     project_root, Result,
 };
 
@@ -34,7 +34,7 @@ fn collect_assists() -> Result<Vec<Assist>> {
 
     fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
         let text = fs::read_to_string(path)?;
-        let comment_blocks = extract_comment_blocks(&text);
+        let comment_blocks = extract_comment_blocks_with_empty_lines(&text);
 
         for block in comment_blocks {
             // FIXME: doesn't support blank lines yet, need to tweak
@@ -45,7 +45,11 @@ fn collect_assists() -> Result<Vec<Assist>> {
                 continue;
             }
             let id = first_line["Assist: ".len()..].to_string();
-            assert!(id.chars().all(|it| it.is_ascii_lowercase() || it == '_'));
+            assert!(
+                id.chars().all(|it| it.is_ascii_lowercase() || it == '_'),
+                "invalid assist id: {:?}",
+                id
+            );
 
             let doc = take_until(lines.by_ref(), "```");
             let before = take_until(lines.by_ref(), "```");