6 files changed, 494 insertions, 1442 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 65cc9fc12..3af01cd6b 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -1,6 +1,6 @@
 # Contributing Quick Start
 
-Rust Analyzer is just a usual rust project, which is organized as a Cargo
+Rust Analyzer is an ordinary Rust project, which is organized as a Cargo
 workspace, builds on stable and doesn't depend on C libraries. So, just
 
 ```
@@ -30,7 +30,7 @@ https://rust-lang.zulipchat.com/#narrow/stream/185405-t-compiler.2Fwg-rls-2.2E0
 
 * [good-first-issue](https://github.com/rust-analyzer/rust-analyzer/labels/good%20first%20issue)
   are good issues to get into the project.
-* [E-mentor](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-mentor)
+* [E-has-instructions](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-has-instructions)
   issues have links to the code in question and tests.
 * [E-easy](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy),
   [E-medium](https://github.com/rust-analyzer/rust-analyzer/issues?q=is%3Aopen+is%3Aissue+label%3AE-medium),
@@ -55,7 +55,7 @@ You can run `cargo xtask install-pre-commit-hook` to install git-hook to run rus
 All Rust code lives in the `crates` top-level directory, and is organized as a
 single Cargo workspace. The `editors` top-level directory contains code for
 integrating with editors. Currently, it contains the plugin for VS Code (in
-typescript). The `docs` top-level directory contains both developer and user
+TypeScript). The `docs` top-level directory contains both developer and user
 documentation.
 
 We have some automation infra in Rust in the `xtask` package. It contains
@@ -65,7 +65,7 @@ directory).
 
 # Launching rust-analyzer
 
-Debugging language server can be tricky: LSP is rather chatty, so driving it
+Debugging the language server can be tricky: LSP is rather chatty, so driving it
 from the command line is not really feasible, driving it via VS Code requires
 interacting with two processes.
 
@@ -73,14 +73,14 @@ For this reason, the best way to see how rust-analyzer works is to find a
 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
+However, launching a VS Code instance with a locally built language server is
 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.
 
-If the problem concerns only internal parts of rust-analyzer (ie, I don't need
-to touch `rust-analyzer` crate or typescript code), there is a unit-test for it.
+If the problem concerns only internal parts of rust-analyzer (i.e. I don't need
+to touch the `rust-analyzer` crate or TypeScript code), there is a unit-test for it.
 So, I use **Rust Analyzer: Run** action in VS Code to run this single test, and
 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
@@ -88,8 +88,8 @@ Code to sanity check that the thing works as I expect.
 
 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:
+`rust-analyzer` binary from `PATH`. For this, it is important to have the following
+in your `settings.json` file:
 ```json
 {
     "rust-analyzer.serverPath": "rust-analyzer"
@@ -107,7 +107,7 @@ things up, sometimes I open a temporary hello-world project which has
 `"rust-analyzer.withSysroot": false` in `.code/settings.json`. This flag causes
 rust-analyzer to skip loading the sysroot, which greatly reduces the amount of
 things rust-analyzer needs to do, and makes printf's more useful. Note that you
-should only use `eprint!` family of macros for debugging: stdout is used for LSP
+should only use the `eprint!` family of macros for debugging: stdout is used for LSP
 communication, and `print!` would break it.
 
 If I need to fix something simultaneously in the server and in the client, I
@@ -117,6 +117,258 @@ Additionally, I use `cargo run --release -p rust-analyzer -- analysis-stats
 path/to/some/rust/crate` to run a batch analysis. This is primarily useful for
 performance optimizations, or for bug minimization.
 
+# Code Style & Review Process
+
+Our approach to "clean code" is two-fold:
+
+* We generally don't block PRs on style changes.
+* At the same time, all code in rust-analyzer is constantly refactored.
+
+It is explicitly OK for a reviewer to flag only some nits in the PR, and then send a follow-up cleanup PR for things which are easier to explain by example, cc-ing the original author.
+Sending small cleanup PRs (like renaming a single local variable) is encouraged.
+
+## Scale of Changes
+
+Everyone knows that it's better to send small & focused pull requests.
+The problem is, sometimes you *have* to, eg, rewrite the whole compiler, and that just doesn't fit into a set of isolated PRs.
+
+The main things to keep an eye on are the boundaries between various components.
+There are three kinds of changes:
+
+1. Internals of a single component are changed.
+   Specifically, you don't change any `pub` items.
+   A good example here would be an addition of a new assist.
+
+2. API of a component is expanded.
+   Specifically, you add a new `pub` function which wasn't there before.
+   A good example here would be expansion of assist API, for example, to implement lazy assists or assists groups.
+
+3. A new dependency between components is introduced.
+   Specifically, you add a `pub use` reexport from another crate or you add a new line to the `[dependencies]` section of `Cargo.toml`.
+   A good example here would be adding reference search capability to the assists crates.
+
+For the first group, the change is generally merged as long as:
+
+* it works for the happy case,
+* it has tests,
+* it doesn't panic for the unhappy case.
+
+For the second group, the change would be subjected to quite a bit of scrutiny and iteration.
+The new API needs to be right (or at least easy to change later).
+The actual implementation doesn't matter that much.
+It's very important to minimize the amount of changed lines of code for changes of the second kind.
+Often, you start doing a change of the first kind, only to realise that you need to elevate to a change of the second kind.
+In this case, we'll probably ask you to split API changes into a separate PR.
+
+Changes of the third group should be pretty rare, so we don't specify any specific process for them.
+That said, adding an innocent-looking `pub use` is a very simple way to break encapsulation, keep an eye on it!
+
+Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate
+https://www.tedinski.com/2018/02/06/system-boundaries.html
+
+## Minimal Tests
+
+Most tests in rust-analyzer start with a snippet of Rust code.
+This snippets should be minimal -- if you copy-paste a snippet of real code into the tests, make sure to remove everything which could be removed.
+There are many benefits to this:
+
+* less to read or to scroll past
+* easier to understand what exactly is tested
+* less stuff printed during printf-debugging
+* less time to run test
+
+It also makes sense to format snippets more compactly (for example, by placing enum defitions like `enum E { Foo, Bar }` on a single line),
+as long as they are still readable.
+
+## Order of Imports
+
+We separate import groups with blank lines
+
+```rust
+mod x;
+mod y;
+
+use std::{ ... }
+
+use crate_foo::{ ... }
+use crate_bar::{ ... }
+
+use crate::{}
+
+use super::{} // but prefer `use crate::`
+```
+
+## Import Style
+
+Items from `hir` and `ast` should be used qualified:
+
+```rust
+// Good
+use ra_syntax::ast;
+
+fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
+
+// Not as good
+use hir::Function;
+use ra_syntax::ast::StructDef;
+
+fn frobnicate(func: Function, strukt: StructDef) {}
+```
+
+Avoid local `use MyEnum::*` imports.
+
+Prefer `use crate::foo::bar` to `use super::bar`.
+
+## Order of Items
+
+Optimize for the reader who sees the file for the first time, and wants to get the general idea about what's going on.
+People read things from top to bottom, so place most important things first.
+
+Specifically, if all items except one are private, always put the non-private item on top.
+
+Put `struct`s and `enum`s first, functions and impls last.
+
+Do
+
+```rust
+// Good
+struct Foo {
+    bars: Vec<Bar>
+}
+
+struct Bar;
+```
+
+rather than
+
+```rust
+// Not as good
+struct Bar;
+
+struct Foo {
+    bars: Vec<Bar>
+}
+```
+
+## Variable Naming
+
+We generally use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)).
+The default name is a lowercased name of the type: `global_state: GlobalState`.
+Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (`db`, `ctx`, `acc`).
+The default name for "result of the function" local variable is `res`.
+
+## Collection types
+
+We prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
+They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount.
+
+## Preconditions
+
+Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee):
+
+```rust
+// Good
+fn frbonicate(walrus: Walrus) {
+    ...
+}
+
+// Not as good
+fn frobnicate(walrus: Option<Walrus>) {
+    let walrus = match walrus {
+        Some(it) => it,
+        None => return,
+    };
+    ...
+}
+```
+
+## Premature Pessimization
+
+While we don't specifically optimize code yet, avoid writing code which is slower than it needs to be.
+Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly.
+
+```rust
+// Good
+use itertools::Itertools;
+
+let (first_word, second_word) = match text.split_ascii_whitespace().collect_tuple() {
+    Some(it) => it,
+    None => return,
+}
+
+// Not as good
+let words = text.split_ascii_whitespace().collect::<Vec<_>>();
+if words.len() != 2 {
+    return
+}
+```
+
+## Documentation
+
+For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
+If the line is too long, you want to split the sentence in two :-)
+
+## Commit Style
+
+We don't have specific rules around git history hygiene.
+Maintaining clean git history is encouraged, but not enforced.
+We use rebase workflow, it's OK to rewrite history during PR review process.
+
+Avoid @mentioning people in commit messages and pull request descriptions (they are added to commit message by bors), as such messages create a lot of duplicate notification traffic during rebases.
+
+# Architecture Invariants
+
+This section tries to document high-level design constraints, which are not
+always obvious from the low-level code.
+
+## Incomplete syntax trees
+
+Syntax trees are by design incomplete and do not enforce well-formedness.
+If an AST method returns an `Option`, it *can* be `None` at runtime, even if this is forbidden by the grammar.
+
+## LSP independence
+
+rust-analyzer is independent from LSP.
+It provides features for a hypothetical perfect Rust-specific IDE client.
+Internal representations are lowered to LSP in the `rust-analyzer` crate (the only crate which is allowed to use LSP types).
+
+## IDE/Compiler split
+
+There's a semi-hard split between "compiler" and "IDE", at the `ra_hir` crate.
+Compiler derives new facts about source code.
+It explicitly acknowledges that not all info is available (i.e. you can't look at types during name resolution).
+
+IDE assumes that all information is available at all times.
+
+IDE should use only types from `ra_hir`, and should not depend on the underling compiler types.
+`ra_hir` is a facade.
+
+## IDE API
+
+The main IDE crate (`ra_ide`) uses "Plain Old Data" for the API.
+Rather than talking in definitions and references, it talks in Strings and textual offsets.
+In general, API is centered around UI concerns -- the result of the call is what the user sees in the editor, and not what the compiler sees underneath.
+The results are 100% Rust specific though.
+
+## Parser Tests
+
+Tests for the parser (`ra_parser`) live in the `ra_syntax` crate (see `test_data` directory).
+There are two kinds of tests:
+
+* Manually written test cases in `parser/ok` and `parser/err`
+* "Inline" tests in `parser/inline` (these are generated) from comments in `ra_parser` crate.
+
+The purpose of inline tests is not to achieve full coverage by test cases, but to explain to the reader of the code what each particular `if` and `match` is responsible for.
+If you are tempted to add a large inline test, it might be a good idea to leave only the simplest example in place, and move the test to a manual `parser/ok` test.
+
+To update test data, run with `UPDATE_EXPECT` variable:
+
+```bash
+env UPDATE_EXPECT=1 cargo qt
+```
+
+After adding a new inline test you need to run `cargo xtest codegen` and also update the test data as described above.
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to
@@ -143,7 +395,7 @@ To log all communication between the server and the client, there are two choice
   [@DJMcNab](https://github.com/DJMcNab) for setting this awesome infra up!
 
 
-There's also two VS Code commands which might be of interest:
+There are also two VS Code commands which might be of interest:
 
 * `Rust Analyzer: Status` shows some memory-usage statistics. To take full
   advantage of it, you need to compile rust-analyzer with jemalloc support:
@@ -159,8 +411,8 @@ There's also two VS Code commands which might be of interest:
   rust code that it refers to and the rust editor will also highlight the proper
   text range.
 
-  If you press <kbd>Ctrl</kbd> (i.e. trigger goto definition) in the inspected
-  Rust source file the syntax tree read-only editor should scroll to and select the
+  If you trigger Go to Definition in the inspected Rust source file,
+  the syntax tree read-only editor should scroll to and select the
   appropriate syntax node token.
 
   ![demo](https://user-images.githubusercontent.com/36276403/78225773-6636a480-74d3-11ea-9d9f-1c9d42da03b0.png)
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index dbc95be38..6d6bbac7c 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -7,6 +7,16 @@ All capabilities are enabled via `experimental` field of `ClientCapabilities` or
 Requests which we hope to upstream live under `experimental/` namespace.
 Requests, which are likely to always remain specific to `rust-analyzer` are under `rust-analyzer/` namespace.
 
+If you want to be notified about the changes to this document, subscribe to [#4604](https://github.com/rust-analyzer/rust-analyzer/issues/4604).
+
+## `initializationOptions`
+
+As `initializationOptions`, `rust-analyzer` expects `"rust-analyzer"` section of the configuration.
+That is, `rust-analyzer` usually sends `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
+`initializationOptions` should contain the same data that would be in the first item of the result.
+It's OK to not send anything, then all the settings would take their default values.
+However, some settings can not be changed after startup at the moment.
+
 ## Snippet `TextEdit`
 
 **Issue:** https://github.com/microsoft/language-server-protocol/issues/724
@@ -87,6 +97,30 @@ Invoking code action at this position will yield two code actions for importing
 * Is a fixed two-level structure enough?
 * Should we devise a general way to encode custom interaction protocols for GUI refactorings?
 
+## Lazy assists with `ResolveCodeAction`
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/787
+
+**Client Capability** `{ "resolveCodeAction": boolean }`
+
+If this capability is set, the assists will be computed lazily. Thus `CodeAction` returned from the server will only contain `id` but not `edit` or `command` fields. The only exclusion from the rule is the diagnostic edits.
+
+After the client got the id, it should then call `experimental/resolveCodeAction` command on the server and provide the following payload:
+
+```typescript
+interface ResolveCodeActionParams {
+    id: string;
+    codeActionParams: lc.CodeActionParams;
+}
+```
+
+As a result of the command call the client will get the respective workspace edit (`lc.WorkspaceEdit`).
+
+### Unresolved Questions
+
+* Apply smarter filtering for ids?
+* Upon `resolveCodeAction` command only call the assits which should be resolved and not all of them?
+
 ## Parent Module
 
 **Issue:** https://github.com/microsoft/language-server-protocol/issues/1002
@@ -301,6 +335,50 @@ Moreover, it would be cool if editors didn't need to implement even basic langua
   This is how `SelectionRange` request works.
 * Alternatively, should we perhaps flag certain `SelectionRange`s as being brace pairs?
 
+## Runnables
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/944
+
+**Server Capability:** `{ "runnables": { "kinds": string[] } }`
+
+This request is send from client to server to get the list of things that can be run (tests, binaries, `cargo check -p`).
+
+**Method:** `experimental/runnables`
+
+**Request:**
+
+```typescript
+interface RunnablesParams {
+    textDocument: TextDocumentIdentifier;
+    /// If null, compute runnables for the whole file.
+    position?: Position;
+}
+```
+
+**Response:** `Runnable[]`
+
+```typescript
+interface Runnable {
+    label: string;
+    /// If this Runnable is associated with a specific function/module, etc, the location of this item
+    location?: LocationLink;
+    /// Running things is necessary technology specific, `kind` needs to be advertised via server capabilities,
+    // the type of `args` is specific to `kind`. The actual running is handled by the client.
+    kind: string;
+    args: any;
+}
+```
+
+rust-analyzer supports only one `kind`, `"cargo"`. The `args` for `"cargo"` look like this:
+
+```typescript
+{
+    workspaceRoot?: string;
+    cargoArgs: string[];
+    executableArgs: string[];
+}
+```
+
 ## Analyzer Status
 
 **Method:** `rust-analyzer/analyzerStatus`
@@ -311,15 +389,27 @@ Moreover, it would be cool if editors didn't need to implement even basic langua
 
 Returns internal status message, mostly for debugging purposes.
 
-## Collect Garbage
+## Reload Workspace
 
-**Method:** `rust-analyzer/collectGarbage`
+**Method:** `rust-analyzer/reloadWorkspace`
 
 **Request:** `null`
 
 **Response:** `null`
 
-Frees some caches. For internal use, and is mostly broken at the moment.
+Reloads project information (that is, re-executes `cargo metadata`).
+
+## Status Notification
+
+**Client Capability:** `{ "statusNotification": boolean }`
+
+**Method:** `rust-analyzer/status`
+
+**Notification:** `"loading" | "ready" | "invalid" | "needsReload"`
+
+This notification is sent from server to client.
+The client can use it to display persistent status to the user (in modline).
+For `needsReload` state, the client can provide a context-menu action to run `rust-analyzer/reloadWorkspace` request.
 
 ## Syntax Tree
 
@@ -390,38 +480,40 @@ interface InlayHint {
 }
 ```
 
-## Runnables
-
-**Method:** `rust-analyzer/runnables`
+## Hover Actions
 
-This request is send from client to server to get the list of things that can be run (tests, binaries, `cargo check -p`).
-Note that we plan to move this request to `experimental/runnables`, as it is not really Rust-specific, but the current API is not necessary the right one.
-Upstream issue: https://github.com/microsoft/language-server-protocol/issues/944
+**Client Capability:** `{ "hoverActions": boolean }`
 
-**Request:**
+If this capability is set, `Hover` request returned from the server might contain an additional field, `actions`:
 
 ```typescript
-interface RunnablesParams {
-    textDocument: TextDocumentIdentifier;
-    /// If null, compute runnables for the whole file.
-    position?: Position;
+interface Hover {
+    ...
+    actions?: CommandLinkGroup[];
 }
-```
 
-**Response:** `Runnable[]`
+interface CommandLink extends Command {
+    /**
+     * A tooltip for the command, when represented in the UI.
+     */
+    tooltip?: string;
+}
 
-```typescript
-interface Runnable {
-    /// The range this runnable is applicable for.
-    range: lc.Range;
-    /// The label to show in the UI.
-    label: string;
-    /// The following fields describe a process to spawn.
-    bin: string;
-    args: string[];
-    /// Args for cargo after `--`.
-    extraArgs: string[];
-    env: { [key: string]: string };
-    cwd: string | null;
+interface CommandLinkGroup {
+    title?: string;
+    commands: CommandLink[];
 }
 ```
+
+Such actions on the client side are appended to a hover bottom as command links:
+```
+  +-----------------------------+
+  | Hover content               |
+  |                             |
+  +-----------------------------+
+  | _Action1_ | _Action2_       |  <- first group, no TITLE
+  +-----------------------------+
+  | TITLE _Action1_ | _Action2_ |  <- second group
+  +-----------------------------+
+  ...
+```
diff --git a/docs/dev/lsp-features.md b/docs/dev/lsp-features.md
deleted file mode 100644
index 00b0867d7..000000000
--- a/docs/dev/lsp-features.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Supported LSP features
-
-This list documents LSP features, supported by rust-analyzer.
-
-## General
-- [x] [initialize](https://microsoft.github.io/language-server-protocol/specification#initialize)
-- [x] [initialized](https://microsoft.github.io/language-server-protocol/specification#initialized)
-- [x] [shutdown](https://microsoft.github.io/language-server-protocol/specification#shutdown)
-- [ ] [exit](https://microsoft.github.io/language-server-protocol/specification#exit)
-- [x] [$/cancelRequest](https://microsoft.github.io/language-server-protocol/specification#cancelRequest)
-
-## Workspace
-- [ ] [workspace/workspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_workspaceFolders)
-- [ ] [workspace/didChangeWorkspaceFolders](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWorkspaceFolders)
-- [x] [workspace/didChangeConfiguration](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeConfiguration)
-- [ ] [workspace/configuration](https://microsoft.github.io/language-server-protocol/specification#workspace_configuration)
-- [x] [workspace/didChangeWatchedFiles](https://microsoft.github.io/language-server-protocol/specification#workspace_didChangeWatchedFiles)
-- [x] [workspace/symbol](https://microsoft.github.io/language-server-protocol/specification#workspace_symbol)
-- [ ] [workspace/applyEdit](https://microsoft.github.io/language-server-protocol/specification#workspace_applyEdit)
-
-## Text Synchronization
-- [x] [textDocument/didOpen](https://microsoft.github.io/language-server-protocol/specification#textDocument_didOpen)
-- [x] [textDocument/didChange](https://microsoft.github.io/language-server-protocol/specification#textDocument_didChange)
-- [ ] [textDocument/willSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSave)
-- [ ] [textDocument/willSaveWaitUntil](https://microsoft.github.io/language-server-protocol/specification#textDocument_willSaveWaitUntil)
-- [x] [textDocument/didSave](https://microsoft.github.io/language-server-protocol/specification#textDocument_didSave)
-- [x] [textDocument/didClose](https://microsoft.github.io/language-server-protocol/specification#textDocument_didClose)
-
-## Diagnostics
-- [x] [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specification#textDocument_publishDiagnostics)
-
-## Lanuguage Features
-- [x] [textDocument/completion](https://microsoft.github.io/language-server-protocol/specification#textDocument_completion)
- - open close: false
- - change: Full
- - will save: false
- - will save wait until: false
- - save: false
-- [x] [completionItem/resolve](https://microsoft.github.io/language-server-protocol/specification#completionItem_resolve)
- - resolve provider: none
- - trigger characters: `:`, `.`
-- [x] [textDocument/hover](https://microsoft.github.io/language-server-protocol/specification#textDocument_hover)
-- [x] [textDocument/signatureHelp](https://microsoft.github.io/language-server-protocol/specification#textDocument_signatureHelp)
- - trigger characters: `(`,  `,`
-- [ ] [textDocument/declaration](https://microsoft.github.io/language-server-protocol/specification#textDocument_declaration)
-- [x] [textDocument/definition](https://microsoft.github.io/language-server-protocol/specification#textDocument_definition)
-- [x] [textDocument/typeDefinition](https://microsoft.github.io/language-server-protocol/specification#textDocument_typeDefinition)
-- [x] [textDocument/implementation](https://microsoft.github.io/language-server-protocol/specification#textDocument_implementation)
-- [x] [textDocument/references](https://microsoft.github.io/language-server-protocol/specification#textDocument_references)
-- [x] [textDocument/documentHighlight](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight)
-- [x] [textDocument/documentSymbol](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentSymbol)
-- [x] [textDocument/codeAction](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeAction)
-- [x] [textDocument/selectionRange](https://github.com/Microsoft/language-server-protocol/issues/613)
- - rust-analyzer.syntaxTree
- - rust-analyzer.matchingBrace
- - rust-analyzer.parentModule
- - rust-analyzer.joinLines
- - rust-analyzer.run
- - rust-analyzer.analyzerStatus
-- [x] [textDocument/codeLens](https://microsoft.github.io/language-server-protocol/specification#textDocument_codeLens)
-- [x] [codeLens/resolve](https://microsoft.github.io/language-server-protocol/specification#codeLens_resolve)
-- [ ] [documentLink/resolve](https://microsoft.github.io/language-server-protocol/specification#documentLink_resolve)
-- [ ] [textDocument/documentColor](https://microsoft.github.io/language-server-protocol/specification#textDocument_documentColor)
-- [ ] [textDocument/colorPresentation](https://microsoft.github.io/language-server-protocol/specification#textDocument_colorPresentation)
-- [x] [textDocument/formatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting)
-- [ ] [textDocument/rangeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_rangeFormatting)
-- [x] [textDocument/onTypeFormatting](https://microsoft.github.io/language-server-protocol/specification#textDocument_onTypeFormatting)
- - first trigger character: `=`
- - more trigger character `.`
-- [x] [textDocument/rename](https://microsoft.github.io/language-server-protocol/specification#textDocument_rename)
-- [x] [textDocument/prepareRename](https://microsoft.github.io/language-server-protocol/specification#textDocument_prepareRename)
-- [x] [textDocument/foldingRange](https://microsoft.github.io/language-server-protocol/specification#textDocument_foldingRange)
diff --git a/docs/user/generated_assists.adoc b/docs/user/generated_assists.adoc
deleted file mode 100644
index 580ab4358..000000000
--- a/docs/user/generated_assists.adoc
+++ /dev/null
@@ -1,1015 +0,0 @@
-[discrete]
-=== `add_custom_impl`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_custom_impl.rs#L14[add_custom_impl.rs]
-
-Adds impl block for derived trait.
-
-.Before
-```rust
-#[derive(Deb┃ug, Display)]
-struct S;
-```
-
-.After
-```rust
-#[derive(Display)]
-struct S;
-
-impl Debug for S {
-    $0
-}
-```
-
-
-[discrete]
-=== `add_derive`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_derive.rs#L9[add_derive.rs]
-
-Adds a new `#[derive()]` clause to a struct or enum.
-
-.Before
-```rust
-struct Point {
-    x: u32,
-    y: u32,┃
-}
-```
-
-.After
-```rust
-#[derive($0)]
-struct Point {
-    x: u32,
-    y: u32,
-}
-```
-
-
-[discrete]
-=== `add_explicit_type`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_explicit_type.rs#L9[add_explicit_type.rs]
-
-Specify type for a let binding.
-
-.Before
-```rust
-fn main() {
-    let x┃ = 92;
-}
-```
-
-.After
-```rust
-fn main() {
-    let x: i32 = 92;
-}
-```
-
-
-[discrete]
-=== `add_from_impl_for_enum`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_from_impl_for_enum.rs#L7[add_from_impl_for_enum.rs]
-
-Adds a From impl for an enum variant with one tuple field.
-
-.Before
-```rust
-enum A { ┃One(u32) }
-```
-
-.After
-```rust
-enum A { One(u32) }
-
-impl From<u32> for A {
-    fn from(v: u32) -> Self {
-        A::One(v)
-    }
-}
-```
-
-
-[discrete]
-=== `add_function`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_function.rs#L19[add_function.rs]
-
-Adds a stub function with a signature matching the function under the cursor.
-
-.Before
-```rust
-struct Baz;
-fn baz() -> Baz { Baz }
-fn foo() {
-    bar┃("", baz());
-}
-
-```
-
-.After
-```rust
-struct Baz;
-fn baz() -> Baz { Baz }
-fn foo() {
-    bar("", baz());
-}
-
-fn bar(arg: &str, baz: Baz) {
-    ${0:todo!()}
-}
-
-```
-
-
-[discrete]
-=== `add_hash`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L65[raw_string.rs]
-
-Adds a hash to a raw string literal.
-
-.Before
-```rust
-fn main() {
-    r#"Hello,┃ World!"#;
-}
-```
-
-.After
-```rust
-fn main() {
-    r##"Hello, World!"##;
-}
-```
-
-
-[discrete]
-=== `add_impl`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_impl.rs#L6[add_impl.rs]
-
-Adds a new inherent impl for a type.
-
-.Before
-```rust
-struct Ctx<T: Clone> {
-    data: T,┃
-}
-```
-
-.After
-```rust
-struct Ctx<T: Clone> {
-    data: T,
-}
-
-impl<T: Clone> Ctx<T> {
-    $0
-}
-```
-
-
-[discrete]
-=== `add_impl_default_members`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_missing_impl_members.rs#L64[add_missing_impl_members.rs]
-
-Adds scaffold for overriding default impl members.
-
-.Before
-```rust
-trait Trait {
-    Type X;
-    fn foo(&self);
-    fn bar(&self) {}
-}
-
-impl Trait for () {
-    Type X = ();
-    fn foo(&self) {}┃
-
-}
-```
-
-.After
-```rust
-trait Trait {
-    Type X;
-    fn foo(&self);
-    fn bar(&self) {}
-}
-
-impl Trait for () {
-    Type X = ();
-    fn foo(&self) {}
-    $0fn bar(&self) {}
-
-}
-```
-
-
-[discrete]
-=== `add_impl_missing_members`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_missing_impl_members.rs#L24[add_missing_impl_members.rs]
-
-Adds scaffold for required impl members.
-
-.Before
-```rust
-trait Trait<T> {
-    Type X;
-    fn foo(&self) -> T;
-    fn bar(&self) {}
-}
-
-impl Trait<u32> for () {┃
-
-}
-```
-
-.After
-```rust
-trait Trait<T> {
-    Type X;
-    fn foo(&self) -> T;
-    fn bar(&self) {}
-}
-
-impl Trait<u32> for () {
-    fn foo(&self) -> u32 {
-        ${0:todo!()}
-    }
-
-}
-```
-
-
-[discrete]
-=== `add_new`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_new.rs#L12[add_new.rs]
-
-Adds a new inherent impl for a type.
-
-.Before
-```rust
-struct Ctx<T: Clone> {
-     data: T,┃
-}
-```
-
-.After
-```rust
-struct Ctx<T: Clone> {
-     data: T,
-}
-
-impl<T: Clone> Ctx<T> {
-    fn $0new(data: T) -> Self { Self { data } }
-}
-
-```
-
-
-[discrete]
-=== `add_turbo_fish`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/add_turbo_fish.rs#L10[add_turbo_fish.rs]
-
-Adds `::<_>` to a call of a generic method or function.
-
-.Before
-```rust
-fn make<T>() -> T { todo!() }
-fn main() {
-    let x = make┃();
-}
-```
-
-.After
-```rust
-fn make<T>() -> T { todo!() }
-fn main() {
-    let x = make::<${0:_}>();
-}
-```
-
-
-[discrete]
-=== `apply_demorgan`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/apply_demorgan.rs#L5[apply_demorgan.rs]
-
-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`.
-
-.Before
-```rust
-fn main() {
-    if x != 4 ||┃ !y {}
-}
-```
-
-.After
-```rust
-fn main() {
-    if !(x == 4 && y) {}
-}
-```
-
-
-[discrete]
-=== `auto_import`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/auto_import.rs#L18[auto_import.rs]
-
-If the name is unresolved, provides all possible imports for it.
-
-.Before
-```rust
-fn main() {
-    let map = HashMap┃::new();
-}
-```
-
-.After
-```rust
-use std::collections::HashMap;
-
-fn main() {
-    let map = HashMap::new();
-}
-```
-
-
-[discrete]
-=== `change_lifetime_anon_to_named`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_lifetime_anon_to_named.rs#L9[change_lifetime_anon_to_named.rs]
-
-Change an anonymous lifetime to a named lifetime.
-
-.Before
-```rust
-impl Cursor<'_┃> {
-    fn node(self) -> &SyntaxNode {
-        match self {
-            Cursor::Replace(node) | Cursor::Before(node) => node,
-        }
-    }
-}
-```
-
-.After
-```rust
-impl<'a> Cursor<'a> {
-    fn node(self) -> &SyntaxNode {
-        match self {
-            Cursor::Replace(node) | Cursor::Before(node) => node,
-        }
-    }
-}
-```
-
-
-[discrete]
-=== `change_return_type_to_result`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_return_type_to_result.rs#L8[change_return_type_to_result.rs]
-
-Change the function's return type to Result.
-
-.Before
-```rust
-fn foo() -> i32┃ { 42i32 }
-```
-
-.After
-```rust
-fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
-```
-
-
-[discrete]
-=== `change_visibility`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/change_visibility.rs#L14[change_visibility.rs]
-
-Adds or changes existing visibility specifier.
-
-.Before
-```rust
-┃fn frobnicate() {}
-```
-
-.After
-```rust
-pub(crate) fn frobnicate() {}
-```
-
-
-[discrete]
-=== `convert_to_guarded_return`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/early_return.rs#L21[early_return.rs]
-
-Replace a large conditional with a guarded return.
-
-.Before
-```rust
-fn main() {
-    ┃if cond {
-        foo();
-        bar();
-    }
-}
-```
-
-.After
-```rust
-fn main() {
-    if !cond {
-        return;
-    }
-    foo();
-    bar();
-}
-```
-
-
-[discrete]
-=== `fill_match_arms`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/fill_match_arms.rs#L14[fill_match_arms.rs]
-
-Adds missing clauses to a `match` expression.
-
-.Before
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        ┃
-    }
-}
-```
-
-.After
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        $0Action::Move { distance } => {}
-        Action::Stop => {}
-    }
-}
-```
-
-
-[discrete]
-=== `fix_visibility`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/fix_visibility.rs#L13[fix_visibility.rs]
-
-Makes inaccessible item public.
-
-.Before
-```rust
-mod m {
-    fn frobnicate() {}
-}
-fn main() {
-    m::frobnicate┃() {}
-}
-```
-
-.After
-```rust
-mod m {
-    $0pub(crate) fn frobnicate() {}
-}
-fn main() {
-    m::frobnicate() {}
-}
-```
-
-
-[discrete]
-=== `flip_binexpr`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_binexpr.rs#L5[flip_binexpr.rs]
-
-Flips operands of a binary expression.
-
-.Before
-```rust
-fn main() {
-    let _ = 90 +┃ 2;
-}
-```
-
-.After
-```rust
-fn main() {
-    let _ = 2 + 90;
-}
-```
-
-
-[discrete]
-=== `flip_comma`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_comma.rs#L5[flip_comma.rs]
-
-Flips two comma-separated items.
-
-.Before
-```rust
-fn main() {
-    ((1, 2),┃ (3, 4));
-}
-```
-
-.After
-```rust
-fn main() {
-    ((3, 4), (1, 2));
-}
-```
-
-
-[discrete]
-=== `flip_trait_bound`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/flip_trait_bound.rs#L9[flip_trait_bound.rs]
-
-Flips two trait bounds.
-
-.Before
-```rust
-fn foo<T: Clone +┃ Copy>() { }
-```
-
-.After
-```rust
-fn foo<T: Copy + Clone>() { }
-```
-
-
-[discrete]
-=== `inline_local_variable`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/inline_local_variable.rs#L13[inline_local_variable.rs]
-
-Inlines local variable.
-
-.Before
-```rust
-fn main() {
-    let x┃ = 1 + 2;
-    x * 4;
-}
-```
-
-.After
-```rust
-fn main() {
-    (1 + 2) * 4;
-}
-```
-
-
-[discrete]
-=== `introduce_variable`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/introduce_variable.rs#L14[introduce_variable.rs]
-
-Extracts subexpression into a variable.
-
-.Before
-```rust
-fn main() {
-    ┃(1 + 2)┃ * 4;
-}
-```
-
-.After
-```rust
-fn main() {
-    let $0var_name = (1 + 2);
-    var_name * 4;
-}
-```
-
-
-[discrete]
-=== `invert_if`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/invert_if.rs#L12[invert_if.rs]
-
-Apply invert_if
-This transforms if expressions of the form `if !x {A} else {B}` into `if x {B} else {A}`
-This also works with `!=`. This assist can only be applied with the cursor
-on `if`.
-
-.Before
-```rust
-fn main() {
-    if┃ !y { A } else { B }
-}
-```
-
-.After
-```rust
-fn main() {
-    if y { B } else { A }
-}
-```
-
-
-[discrete]
-=== `make_raw_string`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L10[raw_string.rs]
-
-Adds `r#` to a plain string literal.
-
-.Before
-```rust
-fn main() {
-    "Hello,┃ World!";
-}
-```
-
-.After
-```rust
-fn main() {
-    r#"Hello, World!"#;
-}
-```
-
-
-[discrete]
-=== `make_usual_string`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L39[raw_string.rs]
-
-Turns a raw string into a plain string.
-
-.Before
-```rust
-fn main() {
-    r#"Hello,┃ "World!""#;
-}
-```
-
-.After
-```rust
-fn main() {
-    "Hello, \"World!\"";
-}
-```
-
-
-[discrete]
-=== `merge_imports`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/merge_imports.rs#L14[merge_imports.rs]
-
-Merges two imports with a common prefix.
-
-.Before
-```rust
-use std::┃fmt::Formatter;
-use std::io;
-```
-
-.After
-```rust
-use std::{fmt::Formatter, io};
-```
-
-
-[discrete]
-=== `merge_match_arms`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/merge_match_arms.rs#L11[merge_match_arms.rs]
-
-Merges identical match arms.
-
-.Before
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        ┃Action::Move(..) => foo(),
-        Action::Stop => foo(),
-    }
-}
-```
-
-.After
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move(..) | Action::Stop => foo(),
-    }
-}
-```
-
-
-[discrete]
-=== `move_arm_cond_to_match_guard`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_guard.rs#L56[move_guard.rs]
-
-Moves if expression from match arm body into a guard.
-
-.Before
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } => ┃if distance > 10 { foo() },
-        _ => (),
-    }
-}
-```
-
-.After
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } if distance > 10 => foo(),
-        _ => (),
-    }
-}
-```
-
-
-[discrete]
-=== `move_bounds_to_where_clause`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_bounds.rs#L10[move_bounds.rs]
-
-Moves inline type bounds to a where clause.
-
-.Before
-```rust
-fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U {
-    f(x)
-}
-```
-
-.After
-```rust
-fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U {
-    f(x)
-}
-```
-
-
-[discrete]
-=== `move_guard_to_arm_body`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/move_guard.rs#L8[move_guard.rs]
-
-Moves match guard into match arm body.
-
-.Before
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } ┃if distance > 10 => foo(),
-        _ => (),
-    }
-}
-```
-
-.After
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } => if distance > 10 { foo() },
-        _ => (),
-    }
-}
-```
-
-
-[discrete]
-=== `remove_dbg`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/remove_dbg.rs#L8[remove_dbg.rs]
-
-Removes `dbg!()` macro call.
-
-.Before
-```rust
-fn main() {
-    ┃dbg!(92);
-}
-```
-
-.After
-```rust
-fn main() {
-    92;
-}
-```
-
-
-[discrete]
-=== `remove_hash`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/raw_string.rs#L89[raw_string.rs]
-
-Removes a hash from a raw string literal.
-
-.Before
-```rust
-fn main() {
-    r#"Hello,┃ World!"#;
-}
-```
-
-.After
-```rust
-fn main() {
-    r"Hello, World!";
-}
-```
-
-
-[discrete]
-=== `remove_mut`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/remove_mut.rs#L5[remove_mut.rs]
-
-Removes the `mut` keyword.
-
-.Before
-```rust
-impl Walrus {
-    fn feed(&mut┃ self, amount: u32) {}
-}
-```
-
-.After
-```rust
-impl Walrus {
-    fn feed(&self, amount: u32) {}
-}
-```
-
-
-[discrete]
-=== `reorder_fields`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/reorder_fields.rs#L10[reorder_fields.rs]
-
-Reorder the fields of record literals and record patterns in the same order as in
-the definition.
-
-.Before
-```rust
-struct Foo {foo: i32, bar: i32};
-const test: Foo = ┃Foo {bar: 0, foo: 1}
-```
-
-.After
-```rust
-struct Foo {foo: i32, bar: i32};
-const test: Foo = Foo {foo: 1, bar: 0}
-```
-
-
-[discrete]
-=== `replace_if_let_with_match`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_if_let_with_match.rs#L13[replace_if_let_with_match.rs]
-
-Replaces `if let` with an else branch with a `match` expression.
-
-.Before
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    ┃if let Action::Move { distance } = action {
-        foo(distance)
-    } else {
-        bar()
-    }
-}
-```
-
-.After
-```rust
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } => foo(distance),
-        _ => bar(),
-    }
-}
-```
-
-
-[discrete]
-=== `replace_let_with_if_let`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_let_with_if_let.rs#L14[replace_let_with_if_let.rs]
-
-Replaces `let` with an `if-let`.
-
-.Before
-```rust
-
-fn main(action: Action) {
-    ┃let x = compute();
-}
-
-fn compute() -> Option<i32> { None }
-```
-
-.After
-```rust
-
-fn main(action: Action) {
-    if let Some(x) = compute() {
-    }
-}
-
-fn compute() -> Option<i32> { None }
-```
-
-
-[discrete]
-=== `replace_qualified_name_with_use`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_qualified_name_with_use.rs#L6[replace_qualified_name_with_use.rs]
-
-Adds a use statement for a given fully-qualified name.
-
-.Before
-```rust
-fn process(map: std::collections::┃HashMap<String, String>) {}
-```
-
-.After
-```rust
-use std::collections::HashMap;
-
-fn process(map: HashMap<String, String>) {}
-```
-
-
-[discrete]
-=== `replace_unwrap_with_match`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/replace_unwrap_with_match.rs#L17[replace_unwrap_with_match.rs]
-
-Replaces `unwrap` a `match` expression. Works for Result and Option.
-
-.Before
-```rust
-enum Result<T, E> { Ok(T), Err(E) }
-fn main() {
-    let x: Result<i32, i32> = Result::Ok(92);
-    let y = x.┃unwrap();
-}
-```
-
-.After
-```rust
-enum Result<T, E> { Ok(T), Err(E) }
-fn main() {
-    let x: Result<i32, i32> = Result::Ok(92);
-    let y = match x {
-        Ok(a) => a,
-        $0_ => unreachable!(),
-    };
-}
-```
-
-
-[discrete]
-=== `split_import`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/split_import.rs#L7[split_import.rs]
-
-Wraps the tail of import into braces.
-
-.Before
-```rust
-use std::┃collections::HashMap;
-```
-
-.After
-```rust
-use std::{collections::HashMap};
-```
-
-
-[discrete]
-=== `unwrap_block`
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_assists/src/handlers/unwrap_block.rs#L9[unwrap_block.rs]
-
-This assist removes if...else, for, while and loop control statements to just keep the body.
-
-.Before
-```rust
-fn foo() {
-    if true {┃
-        println!("foo");
-    }
-}
-```
-
-.After
-```rust
-fn foo() {
-    println!("foo");
-}
-```
diff --git a/docs/user/generated_features.adoc b/docs/user/generated_features.adoc
deleted file mode 100644
index 12812fa0b..000000000
--- a/docs/user/generated_features.adoc
+++ /dev/null
@@ -1,298 +0,0 @@
-=== Expand Macro Recursively
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/expand_macro.rs#L15[expand_macro.rs]
-
-Shows the full macro expansion of the macro at current cursor.
-
-|===
-| Editor  | Action Name
-
-| VS Code | **Rust Analyzer: Expand macro recursively**
-|===
-
-
-=== Extend Selection
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/extend_selection.rs#L15[extend_selection.rs]
-
-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+→]
-|===
-
-
-=== File Structure
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/display/structure.rs#L17[structure.rs]
-
-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]
-|===
-
-
-=== Go to Definition
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_definition.rs#L18[goto_definition.rs]
-
-Navigates to the definition of an identifier.
-
-|===
-| Editor  | Shortcut
-
-| VS Code | kbd:[F12]
-|===
-
-
-=== Go to Implementation
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_implementation.rs#L7[goto_implementation.rs]
-
-Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
-
-|===
-| Editor  | Shortcut
-
-| VS Code | kbd:[Ctrl+F12]
-|===
-
-
-=== Go to Type Definition
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/goto_type_definition.rs#L6[goto_type_definition.rs]
-
-Navigates to the type of an identifier.
-
-|===
-| Editor  | Action Name
-
-| VS Code | **Go to Type Definition*
-|===
-
-
-=== Hover
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/hover.rs#L63[hover.rs]
-
-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.
-
-
-=== Inlay Hints
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/inlay_hints.rs#L40[inlay_hints.rs]
-
-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*
-|===
-
-
-=== Join Lines
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/join_lines.rs#L12[join_lines.rs]
-
-Join selected lines into one, smartly fixing up whitespace, trailing commas, and braces.
-
-|===
-| Editor  | Action Name
-
-| VS Code | **Rust Analyzer: Join lines**
-|===
-
-
-=== Magic Completions
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/completion.rs#L38[completion.rs]
-
-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() {}
-}
-```
-
-
-=== Matching Brace
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/matching_brace.rs#L3[matching_brace.rs]
-
-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**
-|===
-
-
-=== On Typing Assists
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/typing.rs#L35[typing.rs]
-
-Some features trigger on typing certain characters:
-
-- typing `let =` tries to smartly add `;` if `=` is followed by an existing expression
-- Enter inside comments automatically inserts `///`
-- typing `.` in a chain method call auto-indents
-
-
-=== Parent Module
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/parent_module.rs#L12[parent_module.rs]
-
-Navigates to the parent module of the current module.
-
-|===
-| Editor  | Action Name
-
-| VS Code | **Rust Analyzer: Locate parent module**
-|===
-
-
-=== Run
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/runnables.rs#L45[runnables.rs]
-
-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**
-|===
-
-
-=== Semantic Syntax Highlighting
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_highlighting.rs#L33[syntax_highlighting.rs]
-
-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.
-
-
-=== Show Syntax Tree
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/syntax_tree.rs#L9[syntax_tree.rs]
-
-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**
-|===
-
-
-=== Status
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/status.rs#L27[status.rs]
-
-Shows internal statistic about memory usage of rust-analyzer.
-
-|===
-| Editor  | Action Name
-
-| VS Code | **Rust Analyzer: Status**
-|===
-
-
-=== Structural Seach and Replace
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide/src/ssr.rs#L26[ssr.rs]
-
-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**
-|===
-
-
-=== Workspace Symbol
-**Source:** https://github.com/rust-analyzer/rust-analyzer/blob/master/crates/ra_ide_db/src/symbol_index.rs#L113[symbol_index.rs]
-
-Uses fuzzy-search to find types, modules and functions by name across your
-project and dependencies. This is **the** most useful feature, which improves code
-navigation tremendously. It mostly works on top of the built-in LSP
-functionality, however `#` and `*` symbols can be used to narrow down the
-search. Specifically,
-
-- `Foo` searches for `Foo` type in the current workspace
-- `foo#` searches for `foo` function in the current workspace
-- `Foo*` searches for `Foo` type among dependencies, including `stdlib`
-- `foo#*` searches for `foo` function among dependencies
-
-That is, `#` switches from "types" to all symbols, `*` switches from the current
-workspace to dependencies.
-
-|===
-| Editor  | Shortcut
-
-| VS Code | kbd:[Ctrl+T]
-|===
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index 202783fd9..7fab7237b 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -13,8 +13,12 @@ This manual focuses on a specific usage of the library -- running it as part of
 https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP).
 The LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic features like completion or goto definition by talking to an external language server process.
 
-To improve this document, send a pull request against
-https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[this file].
+[TIP]
+====
+[.lead]
+To improve this document, send a pull request: +
+https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[https://github.com/rust-analyzer/.../manual.adoc]
+====
 
 If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum.
 
@@ -57,7 +61,7 @@ To disable this notification put the following to `settings.json`
 The server binary is stored in:
 
 * Linux: `~/.config/Code/User/globalStorage/matklad.rust-analyzer`
-* macOS: `~/Library/Application Support/Code/User/globalStorage/matklad.rust-analyzer`
+* macOS: `~/Library/Application\ Support/Code/User/globalStorage/matklad.rust-analyzer`
 * Windows: `%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer`
 
 Note that we only support two most recent versions of VS Code.
@@ -109,18 +113,6 @@ Here are some useful self-diagnostic commands:
 * 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.
 
-==== Special `when` clause context for keybindings.
-You may use `inRustProject` context to configure keybindings for rust projects only. For example:
-[source,json]
-----
-{
-  "key": "ctrl+i",
-  "command": "rust-analyzer.toggleInlayHints",
-  "when": "inRustProject"
-}
-----
-More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
-
 === rust-analyzer Language Server Binary
 
 Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
@@ -269,6 +261,63 @@ Gnome Builder currently has support for RLS, and there's no way to configure the
 1. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`).
 2. Enable the Rust Builder plugin.
 
+==== GNOME Builder (Nightly)
+
+https://nightly.gnome.org/repo/appstream/org.gnome.Builder.flatpakref[GNOME Builder (Nightly)] has now native support for `rust-analyzer` out of the box. If the `rust-analyzer` binary is not available, GNOME Builder can install it when opening a Rust source file.
+
+== Non-Cargo Based Projects
+
+rust-analyzer does not require Cargo.
+However, if you use some other build system, you'll have to describe the structure of your project for rust-analyzer in the `rust-project.json` format:
+
+[source,TypeScript]
+----
+interface JsonProject {
+   /// The set of paths containing the crates for this project.
+   /// Any `Crate` must be nested inside some `root`.
+   roots: string[];
+   /// The set of crates comprising the current project.
+   /// Must include all transitive dependencies as well as sysroot crate (libstd, libcore and such).
+   crates: Crate[];
+}
+
+interface Crate {
+    /// Path to the root module of the crate.
+    root_module: string;
+    /// Edition of the crate.
+    edition: "2015" | "2018";
+    /// Dependencies
+    deps: Dep[];
+    /// The set of cfgs activated for a given crate, like `["unix", "feature=foo", "feature=bar"]`.
+    cfg: string[];
+
+    /// value of the OUT_DIR env variable.
+    out_dir?: string;
+    /// For proc-macro crates, path to compiles proc-macro (.so file).
+    proc_macro_dylib_path?: string;
+}
+
+interface Dep {
+    /// Index of a crate in the `crates` array.
+    crate: number,
+    /// Name as should appear in the (implicit) `extern crate name` declaration.
+    name: string,
+}
+----
+
+This format is provisional and subject to change.
+Specifically, the `roots` setup will be different eventually.
+
+There are tree ways to feed `rust-project.json` to rust-analyzer:
+
+* Place `rust-project.json` file at the root of the project, and rust-anlayzer will discover it.
+* Specify `"rust-analyzer.linkedProjects": [ "path/to/rust-project.json" ]` in the settings (and make sure that your LSP client sends settings as a part of initialize request).
+* Specify `"rust-analyzer.linkedProjects": [ { "roots": [...], "crates": [...] }]` inline.
+
+Relative paths are interpreted relative to `rust-project.json` file location or (for inline JSON) relative to `rootUri`.
+
+See https://github.com/rust-analyzer/rust-project.json-example for a small example.
+
 == Features
 
 include::./generated_features.adoc[]
@@ -280,3 +329,47 @@ They are usually triggered by a shortcut or by clicking a light bulb icon in the
 Cursor position or selection is signified by `┃` character.
 
 include::./generated_assists.adoc[]
+
+== Editor Features
+=== VS Code
+==== Special `when` clause context for keybindings.
+You may use `inRustProject` context to configure keybindings for rust projects only. For example:
+[source,json]
+----
+{
+  "key": "ctrl+i",
+  "command": "rust-analyzer.toggleInlayHints",
+  "when": "inRustProject"
+}
+----
+More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
+
+==== Setting runnable environment variables
+You can use "rust-analyzer.runnableEnv" setting to define runnable environment-specific substitution variables.
+The simplest way for all runnables in a bunch:
+```jsonc
+"rust-analyzer.runnableEnv": {
+    "RUN_SLOW_TESTS": "1"
+}
+```
+
+Or it is possible to specify vars more granularly:
+```jsonc
+"rust-analyzer.runnableEnv": [
+    {
+        // "mask": null, // null mask means that this rule will be applied for all runnables
+        env: {
+             "APP_ID": "1",
+             "APP_DATA": "asdf"
+        }
+    },
+    {
+        "mask": "test_name",
+        "env": {
+             "APP_ID": "2", // overwrites only APP_ID
+        }
+    }
+]
+```
+
+You can use any valid RegExp as a mask. Also note that a full runnable name is something like *run bin_or_example_name*, *test some::mod::test_name* or *test-mod some::mod*, so it is possible to distinguish binaries, single tests, and test modules with this masks: `"^run"`, `"^test "` (the trailing space matters!), and `"^test-mod"` respectively.