6 files changed, 246 insertions, 24 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index f230dc1db..65cc9fc12 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -74,7 +74,7 @@ relevant test and execute it (VS Code includes an action for running a single
 test).
 
 However, launching a VS Code instance with locally build language server is
-possible. There's **"Run Extension (Dev Server)"** launch configuration for this.
+possible. There's **"Run Extension (Debug Build)"** launch configuration for this.
 
 In general, I use one of the following workflows for fixing bugs and
 implementing features.
@@ -86,7 +86,7 @@ then just do printf-driven development/debugging. As a sanity check after I'm
 done, I use `cargo xtask install --server` and **Reload Window** action in VS
 Code to sanity check that the thing works as I expect.
 
-If the problem concerns only the VS Code extension, I use **Run Extension**
+If the problem concerns only the VS Code extension, I use **Run Installed Extension**
 launch configuration from `launch.json`. Notably, this uses the usual
 `rust-analyzer` binary from `PATH`. For this it is important to have the following
 in `setting.json` file:
@@ -134,7 +134,7 @@ To log all communication between the server and the client, there are two choice
 
 * you can log on the server side, by running something like
   ```
-  env RUST_LOG=gen_lsp_server=trace code .
+  env RA_LOG=gen_lsp_server=trace code .
   ```
 
 * you can log on the client side, by enabling `"rust-analyzer.trace.server":
diff --git a/docs/dev/debugging.md b/docs/dev/debugging.md
index 1aa392935..59a83f7d7 100644
--- a/docs/dev/debugging.md
+++ b/docs/dev/debugging.md
@@ -22,8 +22,8 @@ where **only** the `rust-analyzer` extension being debugged is enabled.
 
 ## Debug TypeScript VSCode extension
 
-- `Run Extension` - runs the extension with the globally installed `rust-analyzer` binary.
-- `Run Extension (Dev Server)` - runs extension with the locally built LSP server (`target/debug/rust-analyzer`).
+- `Run Installed Extension` - runs the extension with the globally installed `rust-analyzer` binary.
+- `Run Extension (Debug Build)` - runs extension with the locally built LSP server (`target/debug/rust-analyzer`).
 
 TypeScript debugging is configured to watch your source edits and recompile.
 To apply changes to an already running debug process, press <kbd>Ctrl+Shift+P</kbd> and run the following command in your `[Extension Development Host]`
@@ -47,7 +47,7 @@ To apply changes to an already running debug process, press <kbd>Ctrl+Shift+P</k
     debug = 2
   ```
 
-- Select `Run Extension (Dev Server)` to run your locally built `target/debug/rust-analyzer`.
+- Select `Run Extension (Debug Build)` to run your locally built `target/debug/rust-analyzer`.
 
 - In the original VSCode window once again select the `Attach To Server` debug configuration.
 
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
new file mode 100644
index 000000000..158d3c599
--- /dev/null
+++ b/docs/dev/lsp-extensions.md
@@ -0,0 +1,172 @@
+# LSP Extensions
+
+This document describes LSP extensions used by rust-analyzer.
+It's a best effort document, when in doubt, consult the source (and send a PR with clarification ;-) ).
+We aim to upstream all non Rust-specific extensions to the protocol, but this is not a top priority.
+All capabilities are enabled via `experimental` field of `ClientCapabilities`.
+
+## Snippet `TextEdit`
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/724
+
+**Client Capability:** `{ "snippetTextEdit": boolean }`
+
+If this capability is set, `WorkspaceEdit`s returned from `codeAction` requests might contain `SnippetTextEdit`s instead of usual `TextEdit`s:
+
+```typescript
+interface SnippetTextEdit extends TextEdit {
+    insertTextFormat?: InsertTextFormat;
+}
+```
+
+```typescript
+export interface TextDocumentEdit {
+        textDocument: VersionedTextDocumentIdentifier;
+        edits: (TextEdit | SnippetTextEdit)[];
+}
+```
+
+When applying such code action, the editor should insert snippet, with tab stops and placeholder.
+At the moment, rust-analyzer guarantees that only a single edit will have `InsertTextFormat.Snippet`.
+
+### Example
+
+"Add `derive`" code action transforms `struct S;` into `#[derive($0)] struct S;`
+
+### Unresolved Questions
+
+* Where exactly are `SnippetTextEdit`s allowed (only in code actions at the moment)?
+* Can snippets span multiple files (so far, no)?
+
+## Join Lines
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/992
+
+**Server Capability:** `{ "joinLines": boolean }`
+
+This request is send from client to server to handle "Join Lines" editor action.
+
+**Method:** `experimental/JoinLines`
+
+**Request:**
+
+```typescript
+interface JoinLinesParams {
+    textDocument: TextDocumentIdentifier,
+    /// Currently active selections/cursor offsets.
+    /// This is an array to support multiple cursors.
+    ranges: Range[],
+}
+```
+
+**Response:**
+
+```typescript
+TextEdit[]
+```
+
+### Example
+
+```rust
+fn main() {
+    /*cursor here*/let x = {
+        92
+    };
+}
+```
+
+`experimental/joinLines` yields (curly braces are automagiacally removed)
+
+```rust
+fn main() {
+    let x = 92;
+}
+```
+
+### Unresolved Question
+
+* What is the position of the cursor after `joinLines`?
+  Currently this is left to editor's discretion, but it might be useful to specify on the server via snippets.
+  However, it then becomes unclear how it works with multi cursor.
+
+## Structural Search Replace (SSR)
+
+**Server Capability:** `{ "ssr": boolean }`
+
+This request is send from client to server to handle structural search replace -- automated syntax tree based transformation of the source.
+
+**Method:** `experimental/ssr`
+
+**Request:**
+
+```typescript
+interface SsrParams {
+    /// Search query.
+    /// The specific syntax is specified outside of the protocol.
+    query: string,
+    /// If true, only check the syntax of the query and don't compute the actual edit.
+    parseOnly: bool,
+}
+```
+
+**Response:**
+
+```typescript
+WorkspaceEdit
+```
+
+### Example
+
+SSR with query `foo($a:expr, $b:expr) ==>> ($a).foo($b)` will transform, eg `foo(y + 5, z)` into `(y + 5).foo(z)`.
+
+### Unresolved Question
+
+* Probably needs search without replace mode
+* Needs a way to limit the scope to certain files.
+
+## `CodeAction` Groups
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/994
+
+**Client Capability:** `{ "codeActionGroup": boolean }`
+
+If this capability is set, `CodeAction` returned from the server contain an additional field, `group`:
+
+```typescript
+interface CodeAction {
+    title: string;
+    group?: string;
+    ...
+}
+```
+
+All code-actions with the same `group` should be grouped under single (extendable) entry in lightbulb menu.
+The set of actions `[ { title: "foo" }, { group: "frobnicate", title: "bar" }, { group: "frobnicate", title: "baz" }]` should be rendered as
+
+```
+💡
+  +-------------+
+  | foo         |
+  +-------------+-----+
+  | frobnicate >| bar |
+  +-------------+-----+
+                | baz |
+                +-----+
+```
+
+Alternatively, selecting `frobnicate` could present a user with an additional menu to choose between `bar` and `baz`.
+
+### Example
+
+```rust
+fn main() {
+    let x: Entry/*cursor here*/ = todo!();
+}
+```
+
+Invoking code action at this position will yield two code actions for importing `Entry` from either `collections::HashMap` or `collection::BTreeMap`, grouped under a single "import" group.
+
+### Unresolved Questions
+
+* Is a fixed two-level structure enough?
+* Should we devise a general way to encode custom interaction protocols for GUI refactorings?
diff --git a/docs/user/assists.md b/docs/user/assists.md
index 692fd4f52..4ad7ea59d 100644
--- a/docs/user/assists.md
+++ b/docs/user/assists.md
@@ -17,7 +17,7 @@ struct S;
 struct S;
 
 impl Debug for S {
-
+    $0
 }
 ```
 
@@ -33,7 +33,7 @@ struct Point {
 }
 
 // AFTER
-#[derive()]
+#[derive($0)]
 struct Point {
     x: u32,
     y: u32,
@@ -77,7 +77,7 @@ fn foo() {
 }
 
 fn bar(arg: &str, baz: Baz) {
-    todo!()
+    ${0:todo!()}
 }
 
 ```
@@ -105,16 +105,16 @@ Adds a new inherent impl for a type.
 ```rust
 // BEFORE
 struct Ctx<T: Clone> {
-     data: T,┃
+    data: T,┃
 }
 
 // AFTER
 struct Ctx<T: Clone> {
-     data: T,
+    data: T,
 }
 
 impl<T: Clone> Ctx<T> {
-
+    $0
 }
 ```
 
@@ -146,7 +146,7 @@ trait Trait {
 impl Trait for () {
     Type X = ();
     fn foo(&self) {}
-    fn bar(&self) {}
+    $0fn bar(&self) {}
 
 }
 ```
@@ -176,7 +176,7 @@ trait Trait<T> {
 
 impl Trait<u32> for () {
     fn foo(&self) -> u32 {
-        todo!()
+        ${0:todo!()}
     }
 
 }
@@ -198,11 +198,29 @@ struct Ctx<T: Clone> {
 }
 
 impl<T: Clone> Ctx<T> {
-    fn new(data: T) -> Self { Self { data } }
+    fn $0new(data: T) -> Self { Self { data } }
 }
 
 ```
 
+## `add_turbo_fish`
+
+Adds `::<_>` to a call of a generic method or function.
+
+```rust
+// BEFORE
+fn make<T>() -> T { todo!() }
+fn main() {
+    let x = make┃();
+}
+
+// AFTER
+fn make<T>() -> T { todo!() }
+fn main() {
+    let x = make::<${0:_}>();
+}
+```
+
 ## `apply_demorgan`
 
 Apply [De Morgan's law](https://en.wikipedia.org/wiki/De_Morgan%27s_laws).
@@ -250,7 +268,7 @@ Change the function's return type to Result.
 fn foo() -> i32┃ { 42i32 }
 
 // AFTER
-fn foo() -> Result<i32, > { Ok(42i32) }
+fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
 ```
 
 ## `change_visibility`
@@ -307,12 +325,34 @@ enum Action { Move { distance: u32 }, Stop }
 
 fn handle(action: Action) {
     match action {
-        Action::Move { distance } => {}
+        $0Action::Move { distance } => {}
         Action::Stop => {}
     }
 }
 ```
 
+## `fix_visibility`
+
+Makes inaccessible item public.
+
+```rust
+// BEFORE
+mod m {
+    fn frobnicate() {}
+}
+fn main() {
+    m::frobnicate┃() {}
+}
+
+// AFTER
+mod m {
+    $0pub(crate) fn frobnicate() {}
+}
+fn main() {
+    m::frobnicate() {}
+}
+```
+
 ## `flip_binexpr`
 
 Flips operands of a binary expression.
@@ -386,7 +426,7 @@ fn main() {
 
 // AFTER
 fn main() {
-    let var_name = (1 + 2);
+    let $0var_name = (1 + 2);
     var_name * 4;
 }
 ```
@@ -693,7 +733,7 @@ fn main() {
     let x: Result<i32, i32> = Result::Ok(92);
     let y = match x {
         Ok(a) => a,
-        _ => unreachable!(),
+        $0_ => unreachable!(),
     };
 }
 ```
diff --git a/docs/user/features.md b/docs/user/features.md
index b9a365fc1..340bce835 100644
--- a/docs/user/features.md
+++ b/docs/user/features.md
@@ -143,9 +143,9 @@ 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 {}`
+- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
 - `expr.match` -> `match expr {}`
-- `expr.while` -> `while expr {}`
+- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
 - `expr.ref` -> `&expr`
 - `expr.refm` -> `&mut expr`
 - `expr.not` -> `!expr`
@@ -161,6 +161,16 @@ There also snippet completions:
 #### Inside Modules
 
 - `tfn` -> `#[test] fn f(){}`
+- `tmod` ->
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_fn() {}
+}
+```
 
 ### Code Highlighting
 
diff --git a/docs/user/readme.adoc b/docs/user/readme.adoc
index f6ce0accf..40ed54809 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/readme.adoc
@@ -63,7 +63,7 @@ The server binary is stored in:
 * macOS: `~/Library/Application Support/Code/User/globalStorage/matklad.rust-analyzer`
 * Windows: `%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer`
 
-Note that we only support the latest version of VS Code.
+Note that we only support two most recent versions of VS Code.
 
 ==== Updates
 
@@ -108,7 +108,7 @@ Here are some useful self-diagnostic commands:
 
 * **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary
 * **Rust Analyzer: Status** prints some statistics about the server, like the few latest LSP requests
-* To enable server-side logging, run with `env RUST_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel.
+* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel.
 * To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel.
 * To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools.
 
@@ -249,7 +249,7 @@ If it worked, you should see "rust-analyzer, Line X, Column Y" on the left side
 
 If you get an error saying `No such file or directory: 'rust-analyzer'`, see the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>> section on installing the language server binary.
 
-=== Gnome Builder
+=== GNOME Builder
 
 Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.