Merge branch 'master' into assists_extract_enum

3 files changed, 83 insertions, 994 deletions

diff --git a/docs/user/assists.md b/docs/user/assists.md
deleted file mode 100644
index 4ad7ea59d..000000000
--- a/docs/user/assists.md
+++ /dev/null
@@ -1,769 +0,0 @@
-# Assists
-
-Cursor position or selection is signified by `┃` character.
-
-
-## `add_custom_impl`
-
-Adds impl block for derived trait.
-
-```rust
-// BEFORE
-#[derive(Deb┃ug, Display)]
-struct S;
-
-// AFTER
-#[derive(Display)]
-struct S;
-
-impl Debug for S {
-    $0
-}
-```
-
-## `add_derive`
-
-Adds a new `#[derive()]` clause to a struct or enum.
-
-```rust
-// BEFORE
-struct Point {
-    x: u32,
-    y: u32,┃
-}
-
-// AFTER
-#[derive($0)]
-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_function`
-
-Adds a stub function with a signature matching the function under the cursor.
-
-```rust
-// BEFORE
-struct Baz;
-fn baz() -> Baz { Baz }
-fn foo() {
-    bar┃("", baz());
-}
-
-
-// AFTER
-struct Baz;
-fn baz() -> Baz { Baz }
-fn foo() {
-    bar("", baz());
-}
-
-fn bar(arg: &str, baz: Baz) {
-    ${0:todo!()}
-}
-
-```
-
-## `add_hash`
-
-Adds a hash to a raw string literal.
-
-```rust
-// BEFORE
-fn main() {
-    r#"Hello,┃ World!"#;
-}
-
-// AFTER
-fn main() {
-    r##"Hello, World!"##;
-}
-```
-
-## `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> {
-    $0
-}
-```
-
-## `add_impl_default_members`
-
-Adds scaffold for overriding default impl members.
-
-```rust
-// BEFORE
-trait Trait {
-    Type X;
-    fn foo(&self);
-    fn bar(&self) {}
-}
-
-impl Trait for () {
-    Type X = ();
-    fn foo(&self) {}┃
-
-}
-
-// AFTER
-trait Trait {
-    Type X;
-    fn foo(&self);
-    fn bar(&self) {}
-}
-
-impl Trait for () {
-    Type X = ();
-    fn foo(&self) {}
-    $0fn bar(&self) {}
-
-}
-```
-
-## `add_impl_missing_members`
-
-Adds scaffold for required impl members.
-
-```rust
-// BEFORE
-trait Trait<T> {
-    Type X;
-    fn foo(&self) -> T;
-    fn bar(&self) {}
-}
-
-impl Trait<u32> for () {┃
-
-}
-
-// AFTER
-trait Trait<T> {
-    Type X;
-    fn foo(&self) -> T;
-    fn bar(&self) {}
-}
-
-impl Trait<u32> for () {
-    fn foo(&self) -> u32 {
-        ${0:todo!()}
-    }
-
-}
-```
-
-## `add_new`
-
-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> {
-    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).
-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) {}
-}
-```
-
-## `auto_import`
-
-If the name is unresolved, provides all possible imports for it.
-
-```rust
-// BEFORE
-fn main() {
-    let map = HashMap┃::new();
-}
-
-// AFTER
-use std::collections::HashMap;
-
-fn main() {
-    let map = HashMap::new();
-}
-```
-
-## `change_return_type_to_result`
-
-Change the function's return type to Result.
-
-```rust
-// BEFORE
-fn foo() -> i32┃ { 42i32 }
-
-// AFTER
-fn foo() -> Result<i32, ${0:_}> { Ok(42i32) }
-```
-
-## `change_visibility`
-
-Adds or changes existing visibility specifier.
-
-```rust
-// BEFORE
-┃fn frobnicate() {}
-
-// AFTER
-pub(crate) fn frobnicate() {}
-```
-
-## `convert_to_guarded_return`
-
-Replace a large conditional with a guarded return.
-
-```rust
-// BEFORE
-fn main() {
-    ┃if cond {
-        foo();
-        bar();
-    }
-}
-
-// AFTER
-fn main() {
-    if !cond {
-        return;
-    }
-    foo();
-    bar();
-}
-```
-
-## `fill_match_arms`
-
-Adds missing clauses to a `match` expression.
-
-```rust
-// BEFORE
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        ┃
-    }
-}
-
-// AFTER
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        $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.
-
-```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));
-}
-```
-
-## `flip_trait_bound`
-
-Flips two trait bounds.
-
-```rust
-// BEFORE
-fn foo<T: Clone +┃ Copy>() { }
-
-// AFTER
-fn foo<T: Copy + Clone>() { }
-```
-
-## `inline_local_variable`
-
-Inlines local variable.
-
-```rust
-// BEFORE
-fn main() {
-    let x┃ = 1 + 2;
-    x * 4;
-}
-
-// AFTER
-fn main() {
-    (1 + 2) * 4;
-}
-```
-
-## `introduce_variable`
-
-Extracts subexpression into a variable.
-
-```rust
-// BEFORE
-fn main() {
-    ┃(1 + 2)┃ * 4;
-}
-
-// AFTER
-fn main() {
-    let $0var_name = (1 + 2);
-    var_name * 4;
-}
-```
-
-## `invert_if`
-
-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`.
-
-```rust
-// BEFORE
-fn main() {
-    if┃ !y { A } else { B }
-}
-
-// AFTER
-fn main() {
-    if y { B } else { A }
-}
-```
-
-## `make_raw_string`
-
-Adds `r#` to a plain string literal.
-
-```rust
-// BEFORE
-fn main() {
-    "Hello,┃ World!";
-}
-
-// AFTER
-fn main() {
-    r#"Hello, World!"#;
-}
-```
-
-## `make_usual_string`
-
-Turns a raw string into a plain string.
-
-```rust
-// BEFORE
-fn main() {
-    r#"Hello,┃ "World!""#;
-}
-
-// AFTER
-fn main() {
-    "Hello, \"World!\"";
-}
-```
-
-## `merge_imports`
-
-Merges two imports with a common prefix.
-
-```rust
-// BEFORE
-use std::┃fmt::Formatter;
-use std::io;
-
-// AFTER
-use std::{fmt::Formatter, io};
-```
-
-## `merge_match_arms`
-
-Merges identical match arms.
-
-```rust
-// BEFORE
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        ┃Action::Move(..) => foo(),
-        Action::Stop => foo(),
-    }
-}
-
-// AFTER
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move(..) | Action::Stop => foo(),
-    }
-}
-```
-
-## `move_arm_cond_to_match_guard`
-
-Moves if expression from match arm body into a guard.
-
-```rust
-// BEFORE
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } => ┃if distance > 10 { foo() },
-        _ => (),
-    }
-}
-
-// AFTER
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } if distance > 10 => foo(),
-        _ => (),
-    }
-}
-```
-
-## `move_bounds_to_where_clause`
-
-Moves inline type bounds to a where clause.
-
-```rust
-// BEFORE
-fn apply<T, U, ┃F: FnOnce(T) -> U>(f: F, x: T) -> U {
-    f(x)
-}
-
-// AFTER
-fn apply<T, U, F>(f: F, x: T) -> U where F: FnOnce(T) -> U {
-    f(x)
-}
-```
-
-## `move_guard_to_arm_body`
-
-Moves match guard into match arm body.
-
-```rust
-// BEFORE
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } ┃if distance > 10 => foo(),
-        _ => (),
-    }
-}
-
-// AFTER
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } => if distance > 10 { foo() },
-        _ => (),
-    }
-}
-```
-
-## `remove_dbg`
-
-Removes `dbg!()` macro call.
-
-```rust
-// BEFORE
-fn main() {
-    ┃dbg!(92);
-}
-
-// AFTER
-fn main() {
-    92;
-}
-```
-
-## `remove_hash`
-
-Removes a hash from a raw string literal.
-
-```rust
-// BEFORE
-fn main() {
-    r#"Hello,┃ World!"#;
-}
-
-// AFTER
-fn main() {
-    r"Hello, World!";
-}
-```
-
-## `remove_mut`
-
-Removes the `mut` keyword.
-
-```rust
-// BEFORE
-impl Walrus {
-    fn feed(&mut┃ self, amount: u32) {}
-}
-
-// AFTER
-impl Walrus {
-    fn feed(&self, amount: u32) {}
-}
-```
-
-## `reorder_fields`
-
-Reorder the fields of record literals and record patterns in the same order as in
-the definition.
-
-```rust
-// BEFORE
-struct Foo {foo: i32, bar: i32};
-const test: Foo = ┃Foo {bar: 0, foo: 1}
-
-// AFTER
-struct Foo {foo: i32, bar: i32};
-const test: Foo = Foo {foo: 1, bar: 0}
-```
-
-## `replace_if_let_with_match`
-
-Replaces `if let` with an else branch with a `match` expression.
-
-```rust
-// BEFORE
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    ┃if let Action::Move { distance } = action {
-        foo(distance)
-    } else {
-        bar()
-    }
-}
-
-// AFTER
-enum Action { Move { distance: u32 }, Stop }
-
-fn handle(action: Action) {
-    match action {
-        Action::Move { distance } => foo(distance),
-        _ => bar(),
-    }
-}
-```
-
-## `replace_let_with_if_let`
-
-Replaces `let` with an `if-let`.
-
-```rust
-// BEFORE
-
-fn main(action: Action) {
-    ┃let x = compute();
-}
-
-fn compute() -> Option<i32> { None }
-
-// AFTER
-
-fn main(action: Action) {
-    if let Some(x) = compute() {
-    }
-}
-
-fn compute() -> Option<i32> { None }
-```
-
-## `replace_qualified_name_with_use`
-
-Adds a use statement for a given fully-qualified name.
-
-```rust
-// BEFORE
-fn process(map: std::collections::┃HashMap<String, String>) {}
-
-// AFTER
-use std::collections::HashMap;
-
-fn process(map: HashMap<String, String>) {}
-```
-
-## `replace_unwrap_with_match`
-
-Replaces `unwrap` a `match` expression. Works for Result and Option.
-
-```rust
-// BEFORE
-enum Result<T, E> { Ok(T), Err(E) }
-fn main() {
-    let x: Result<i32, i32> = Result::Ok(92);
-    let y = x.┃unwrap();
-}
-
-// AFTER
-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!(),
-    };
-}
-```
-
-## `split_import`
-
-Wraps the tail of import into braces.
-
-```rust
-// BEFORE
-use std::┃collections::HashMap;
-
-// AFTER
-use std::{collections::HashMap};
-```
-
-## `unwrap_block`
-
-This assist removes if...else, for, while and loop control statements to just keep the body.
-
-```rust
-// BEFORE
-fn foo() {
-    if true {┃
-        println!("foo");
-    }
-}
-
-// AFTER
-fn foo() {
-    println!("foo");
-}
-```
diff --git a/docs/user/features.md b/docs/user/features.md
deleted file mode 100644
index 340bce835..000000000
--- a/docs/user/features.md
+++ /dev/null
@@ -1,212 +0,0 @@
-This document is an index of features that the rust-analyzer language server
-provides. Shortcuts are for the default VS Code layout. If there's no shortcut,
-you can use <kbd>Ctrl+Shift+P</kbd> to search for the corresponding action.
-
-### Workspace Symbol <kbd>ctrl+t</kbd>
-
-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.
-
-### Document Symbol <kbd>ctrl+shift+o</kbd>
-
-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
-
-### On Typing Assists
-
-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
-
-### Extend Selection
-
-Extends the current selection to the encompassing syntactic construct
-(expression, statement, item, module, etc). It works with multiple cursors. This
-is a relatively new feature of LSP:
-https://github.com/Microsoft/language-server-protocol/issues/613, check your
-editor's LSP library to see if this feature is supported.
-
-### Go to Definition
-
-Navigates to the definition of an identifier.
-
-### Go to Implementation
-
-Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
-
-### Go to Type Defintion
-
-Navigates to the type of an identifier.
-
-### Commands <kbd>ctrl+shift+p</kbd>
-
-#### Run
-
-Shows a popup suggesting to run a test/benchmark/binary **at the current cursor
-location**. Super useful for repeatedly running just a single test. Do bind this
-to a shortcut!
-
-#### Parent Module
-
-Navigates to the parent module of the current module.
-
-#### Matching Brace
-
-If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
-moves cursor to the matching brace. It uses the actual parser to determine
-braces, so it won't confuse generics with comparisons.
-
-#### Join Lines
-
-Join selected lines into one, smartly fixing up whitespace and trailing commas.
-
-#### Show Syntax Tree
-
-Shows the parse tree of the current file. It exists mostly for debugging
-rust-analyzer itself.
-
-#### Expand Macro Recursively
-
-Shows the full macro expansion of the macro at current cursor.
-
-#### Status
-
-Shows internal statistic about memory usage of rust-analyzer.
-
-#### Show RA Version
-
-Show current rust-analyzer version.
-
-#### Run Garbage Collection
-
-Manually triggers GC.
-
-#### Start Cargo Watch
-
-Start `cargo watch` for live error highlighting. Will prompt to install if it's not already installed.
-
-#### Stop Cargo Watch
-
-Stop `cargo watch`.
-
-#### Structural Seach and Replace
-
-Search and replace with named wildcards that will match any expression.
-The syntax for a structural search replace command is `<search_pattern> ==>> <replace_pattern>`. A `$<name>:expr` placeholder in the search pattern will match any expression and `$<name>` will reference it in the replacement. Available via the command `rust-analyzer.ssr`.
-
-```rust
-// Using structural search replace command [foo($a:expr, $b:expr) ==>> ($a).foo($b)]
-
-// BEFORE
-String::from(foo(y + 5, z))
-
-// AFTER
-String::from((y + 5).foo(z))
-```
-
-### Assists (Code Actions)
-
-Assists, or code actions, are small local refactorings, available in a particular context.
-They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
-
-See [assists.md](./assists.md) for the list of available assists.
-
-### Magic Completions
-
-In addition to usual reference completion, rust-analyzer provides some ✨magic✨
-completions as well:
-
-Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
-is placed at the appropriate position. Even though `if` is easy to type, you
-still want to complete it, to get ` { }` for free! `return` is inserted with a
-space or `;` depending on the return type of the function.
-
-When completing a function call, `()` are automatically inserted. If a function
-takes arguments, the cursor is positioned inside the parenthesis.
-
-There are postfix completions, which can be triggered by typing something like
-`foo().if`. The word after `.` determines postfix completion. Possible variants are:
-
-- `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
-- `expr.match` -> `match expr {}`
-- `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
-- `expr.ref` -> `&expr`
-- `expr.refm` -> `&mut expr`
-- `expr.not` -> `!expr`
-- `expr.dbg` -> `dbg!(expr)`
-
-There also snippet completions:
-
-#### Inside Expressions
-
-- `pd` -> `println!("{:?}")`
-- `ppd` -> `println!("{:#?}")`
-
-#### Inside Modules
-
-- `tfn` -> `#[test] fn f(){}`
-- `tmod` ->
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_fn() {}
-}
-```
-
-### Code Highlighting
-
-Experimental feature to let rust-analyzer highlight Rust code instead of using the
-default highlighter.
-
-#### Rainbow Highlighting
-
-Experimental feature that, given code highlighting using rust-analyzer is
-active, will pick unique colors for identifiers.
-
-### Code hints
-
-Rust-analyzer has two types of hints to show the information about the code:
-
-* hover hints, appearing on hover on any element.
-
-These contain extended information on the hovered language item.
-
-* inlay hints, shown near the element hinted directly in the editor.
-
-Two types of inlay hints are displayed currently:
-
-* type hints, displaying the minimal information on the type of the expression (if the information is available)
-* method chaining hints, type information for multi-line method chains
-* parameter name hints, displaying the names of the parameters in the corresponding methods
-
-#### VS Code
-
-In VS Code, the following settings can be used to configure the inlay hints:
-
-* `rust-analyzer.inlayHints.typeHints` - enable hints for inferred types.
-* `rust-analyzer.inlayHints.chainingHints` - enable hints for inferred types on method chains.
-* `rust-analyzer.inlayHints.parameterHints` - enable hints for function parameters.
-* `rust-analyzer.inlayHints.maxLength` — shortens the hints if their length exceeds the value specified. If no value is specified (`null`), no shortening is applied.
-
-**Note:** VS Code does not have native support for inlay hints [yet](https://github.com/microsoft/vscode/issues/16221) 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:
-[1](https://github.com/rust-analyzer/rust-analyzer/issues/1623), [2](https://github.com/rust-analyzer/rust-analyzer/issues/3453).
diff --git a/docs/user/readme.adoc b/docs/user/manual.adoc
index 40ed54809..ea714f49a 100644
--- a/docs/user/readme.adoc
+++ b/docs/user/manual.adoc
@@ -2,14 +2,9 @@
 :toc: preamble
 :sectanchors:
 :page-layout: post
-// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions
-:tip-caption: :bulb:
-:note-caption: :information_source:
-:important-caption: :heavy_exclamation_mark:
-:caution-caption: :fire:
-:warning-caption: :warning:
-
-
+:icons: font
+:source-highlighter: rouge
+:experimental:
 
 // Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
 
@@ -19,7 +14,9 @@ https://microsoft.github.io/language-server-protocol/[Language Server Protocol]
 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/readme.adoc[this file].
+https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[this file].
+
+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.
 
 == Installation
 
@@ -112,10 +109,23 @@ 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`.
-You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page. Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`.
+You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page.
+Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`.
 
 On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used
 
@@ -135,7 +145,8 @@ $ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyz
 $ cargo xtask install --server
 ----
 
-If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue]. On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help.
+If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue].
+On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help.
 
 ==== Arch Linux
 
@@ -258,6 +269,65 @@ 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.
 
-== Usage
+== 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.
+
+See https://github.com/rust-analyzer/rust-project.json-example for a small example.
+
+== Features
+
+include::./generated_features.adoc[]
+
+== Assists (Code Actions)
+
+Assists, or code actions, are small local refactorings, available in a particular context.
+They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
+Cursor position or selection is signified by `┃` character.
 
-See https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md].
+include::./generated_assists.adoc[]