10 files changed, 165 insertions, 15 deletions
diff --git a/crates/ra_assists/src/assists/add_explicit_type.rs b/crates/ra_assists/src/assists/add_explicit_type.rs
index 302b9557908..2903c178193 100644
--- a/crates/ra_assists/src/assists/add_explicit_type.rs
+++ b/crates/ra_assists/src/assists/add_explicit_type.rs
@@ -8,7 +8,7 @@ use crate::{Assist, AssistCtx, AssistId};
 
 // Assist: add_explicit_type
 //
-// Specify type for a let binding
+// Specify type for a let binding.
 //
 // ```
 // fn main() {
diff --git a/crates/ra_assists/src/assists/add_impl.rs b/crates/ra_assists/src/assists/add_impl.rs
index 43aeac7bd6e..142777b0674 100644
--- a/crates/ra_assists/src/assists/add_impl.rs
+++ b/crates/ra_assists/src/assists/add_impl.rs
@@ -10,7 +10,7 @@ use crate::{Assist, AssistCtx, AssistId};
 
 // Assist: add_impl
 //
-// Adds a new inherent impl for a type
+// Adds a new inherent impl for a type.
 //
 // ```
 // struct Ctx<T: Clone> {
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 fe1f2e72e7f..4ee4d47faca 100644
--- a/crates/ra_assists/src/assists/add_missing_impl_members.rs
+++ b/crates/ra_assists/src/assists/add_missing_impl_members.rs
@@ -14,7 +14,7 @@ enum AddMissingImplMembersMode {
 
 // Assist: add_impl_missing_members
 //
-// Adds scaffold for required impl members
+// Adds scaffold for required impl members.
 //
 // ```
 // trait T {
@@ -50,7 +50,9 @@ pub(crate) fn add_missing_impl_members(ctx: AssistCtx<impl HirDatabase>) -> Opti
 }
 
 // Assist: add_impl_default_members
-// Adds scaffold for overriding default impl members
+//
+// Adds scaffold for overriding default impl members.
+//
 // ```
 // trait T {
 //     Type X;
diff --git a/crates/ra_assists/src/assists/early_return.rs b/crates/ra_assists/src/assists/early_return.rs
index b3d0253406c..48782db4221 100644
--- a/crates/ra_assists/src/assists/early_return.rs
+++ b/crates/ra_assists/src/assists/early_return.rs
@@ -14,7 +14,9 @@ use crate::{
 };
 
 // Assist: convert_to_guarded_return
+//
 // Replace a large conditional with a guarded return.
+//
 // ```
 // fn main() {
 //     <|>if cond {
diff --git a/crates/ra_assists/src/assists/flip_binexpr.rs b/crates/ra_assists/src/assists/flip_binexpr.rs
index c5103528230..3a1e5cbe1b1 100644
--- a/crates/ra_assists/src/assists/flip_binexpr.rs
+++ b/crates/ra_assists/src/assists/flip_binexpr.rs
@@ -1,11 +1,23 @@
-//! FIXME: write short doc here
-
 use hir::db::HirDatabase;
 use ra_syntax::ast::{AstNode, BinExpr, BinOp};
 
 use crate::{Assist, AssistCtx, AssistId};
 
-/// Flip binary expression assist.
+// Assist: flip_binexpr
+//
+// Flips operands of a binary expression.
+//
+// ```
+// fn main() {
+//     let _ = 90 +<|> 2;
+// }
+// ```
+// ->
+// ```
+// fn main() {
+//     let _ = 2 + 90;
+// }
+// ```
 pub(crate) fn flip_binexpr(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let expr = ctx.node_at_offset::<BinExpr>()?;
     let lhs = expr.lhs()?.syntax().clone();
diff --git a/crates/ra_assists/src/assists/flip_comma.rs b/crates/ra_assists/src/assists/flip_comma.rs
index e31cc5e7d70..d06c5a0e18b 100644
--- a/crates/ra_assists/src/assists/flip_comma.rs
+++ b/crates/ra_assists/src/assists/flip_comma.rs
@@ -1,10 +1,23 @@
-//! FIXME: write short doc here
-
 use hir::db::HirDatabase;
 use ra_syntax::{algo::non_trivia_sibling, Direction, T};
 
 use crate::{Assist, AssistCtx, AssistId};
 
+// Assist: flip_comma
+//
+// Flips two comma-separated items.
+//
+// ```
+// fn main() {
+//     ((1, 2),<|> (3, 4));
+// }
+// ```
+// ->
+// ```
+// fn main() {
+//     ((3, 4), (1, 2));
+// }
+// ```
 pub(crate) fn flip_comma(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let comma = ctx.token_at_offset().find(|leaf| leaf.kind() == T![,])?;
     let prev = non_trivia_sibling(comma.clone().into(), Direction::Prev)?;
diff --git a/crates/ra_assists/src/assists/inline_local_variable.rs b/crates/ra_assists/src/assists/inline_local_variable.rs
index 9bd64decc9d..1997781dbbc 100644
--- a/crates/ra_assists/src/assists/inline_local_variable.rs
+++ b/crates/ra_assists/src/assists/inline_local_variable.rs
@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::db::HirDatabase;
 use ra_syntax::{
     ast::{self, AstNode, AstToken},
@@ -9,6 +7,22 @@ use ra_syntax::{
 use crate::assist_ctx::AssistBuilder;
 use crate::{Assist, AssistCtx, AssistId};
 
+// Assist: inline_local_variable
+//
+// Inlines local variable.
+//
+// ```
+// fn main() {
+//     let x<|> = 1 + 2;
+//     x * 4;
+// }
+// ```
+// ->
+// ```
+// fn main() {
+//     (1 + 2) * 4;
+// }
+// ```
 pub(crate) fn inline_local_varialbe(mut ctx: AssistCtx<impl HirDatabase>) -> Option<Assist> {
     let let_stmt = ctx.node_at_offset::<ast::LetStmt>()?;
     let bind_pat = match let_stmt.pat()? {
diff --git a/crates/ra_assists/src/doc_tests/generated.rs b/crates/ra_assists/src/doc_tests/generated.rs
index 43fa159d7df..d390db33cfe 100644
--- a/crates/ra_assists/src/doc_tests/generated.rs
+++ b/crates/ra_assists/src/doc_tests/generated.rs
@@ -203,3 +203,55 @@ fn handle(action: Action) {
 "#####,
     )
 }
+
+#[test]
+fn doctest_flip_binexpr() {
+    check(
+        "flip_binexpr",
+        r#####"
+fn main() {
+    let _ = 90 +<|> 2;
+}
+"#####,
+        r#####"
+fn main() {
+    let _ = 2 + 90;
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_flip_comma() {
+    check(
+        "flip_comma",
+        r#####"
+fn main() {
+    ((1, 2),<|> (3, 4));
+}
+"#####,
+        r#####"
+fn main() {
+    ((3, 4), (1, 2));
+}
+"#####,
+    )
+}
+
+#[test]
+fn doctest_inline_local_variable() {
+    check(
+        "inline_local_variable",
+        r#####"
+fn main() {
+    let x<|> = 1 + 2;
+    x * 4;
+}
+"#####,
+        r#####"
+fn main() {
+    (1 + 2) * 4;
+}
+"#####,
+    )
+}
diff --git a/docs/user/assists.md b/docs/user/assists.md
index 603b29c6614..8e2e8cc9457 100644
--- a/docs/user/assists.md
+++ b/docs/user/assists.md
@@ -21,7 +21,7 @@ struct Point {
 
 ## `add_explicit_type`
 
-Specify type for a let binding
+Specify type for a let binding.
 
 ```rust
 // BEFORE
@@ -37,7 +37,7 @@ fn main() {
 
 ## `add_impl`
 
-Adds a new inherent impl for a type
+Adds a new inherent impl for a type.
 
 ```rust
 // BEFORE
@@ -57,7 +57,7 @@ impl<T: Clone> Ctx<T> {
 
 ## `add_impl_default_members`
 
-Adds scaffold for overriding default impl members
+Adds scaffold for overriding default impl members.
 
 ```rust
 // BEFORE
@@ -90,7 +90,7 @@ impl T for () {
 
 ## `add_impl_missing_members`
 
-Adds scaffold for required impl members
+Adds scaffold for required impl members.
 
 ```rust
 // BEFORE
@@ -196,3 +196,52 @@ fn handle(action: Action) {
     }
 }
 ```
+
+## `flip_binexpr`
+
+Flips operands of a binary expression.
+
+```rust
+// BEFORE
+fn main() {
+    let _ = 90 +<|> 2;
+}
+
+// AFTER
+fn main() {
+    let _ = 2 + 90;
+}
+```
+
+## `flip_comma`
+
+Flips two comma-separated items.
+
+```rust
+// BEFORE
+fn main() {
+    ((1, 2),<|> (3, 4));
+}
+
+// AFTER
+fn main() {
+    ((3, 4), (1, 2));
+}
+```
+
+## `inline_local_variable`
+
+Inlines local variable.
+
+```rust
+// BEFORE
+fn main() {
+    let x<|> = 1 + 2;
+    x * 4;
+}
+
+// AFTER
+fn main() {
+    (1 + 2) * 4;
+}
+```
diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs
index 2ca7cda63db..8dca2ed06e3 100644
--- a/xtask/src/codegen/gen_assists_docs.rs
+++ b/xtask/src/codegen/gen_assists_docs.rs
@@ -52,6 +52,12 @@ fn collect_assists() -> Result<Vec<Assist>> {
             );
 
             let doc = take_until(lines.by_ref(), "```").trim().to_string();
+            assert!(
+                doc.chars().next().unwrap().is_ascii_uppercase() && doc.ends_with("."),
+                "\n\n{}: assist docs should be proper sentences, with capitalization and a full stop at the end.\n\n{}\n\n",
+                id, doc,
+            );
+
             let before = take_until(lines.by_ref(), "```");
 
             assert_eq!(lines.next().unwrap().as_str(), "->");