5 files changed, 146 insertions, 43 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 6b6824ded..417352c9d 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -177,6 +177,9 @@ There are many benefits to this:
 * 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
@@ -311,7 +314,7 @@ 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, as such messages create a lot of duplicate notification traffic during rebases.
+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
 
@@ -358,14 +361,24 @@ There are two kinds of tests:
 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_EXPECTATIONS` variable:
+To update test data, run with `UPDATE_EXPECT` variable:
 
 ```bash
-env UPDATE_EXPECTATIONS=1 cargo qt
+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.
 
+## TypeScript Tests
+
+If you change files under `editors/code` and would like to run the tests and linter, install npm and run:
+
+```bash
+cd editors/code
+npm ci
+npm run lint
+```
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to
@@ -394,13 +407,7 @@ To log all communication between the server and the client, there are two choice
 
 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:
-  ```
-  $ cargo install --path crates/rust-analyzer --force --features jemalloc
-  ```
-
-  There's an alias for this: `cargo xtask install --server --jemalloc`.
+* `Rust Analyzer: Status` shows some memory-usage statistics.
 
 * `Rust Analyzer: Syntax Tree` shows syntax tree of the current file/selection.
 
diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index cee916c09..d0c6eea61 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -170,8 +170,7 @@ The innermost and most elaborate boundary is `hir`. It has a much richer
 vocabulary of types than `ide`, but the basic testing setup is the same: we
 create a database, run some queries, assert result.
 
-For comparisons, we use [insta](https://github.com/mitsuhiko/insta/) library for
-snapshot testing.
+For comparisons, we use the `expect` crate for snapshot testing.
 
 To test various analysis corner cases and avoid forgetting about old tests, we
 use so-called marks. See the `marks` module in the `test_utils` crate for more.
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index a0847dad3..1be01fd88 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -11,11 +11,13 @@ If you want to be notified about the changes to this document, subscribe to [#46
 
 ## `initializationOptions`
 
-As `initializationOptions`, `rust-analyzer` expects `"rust-analyzer"` section of the configuration.
+For `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.
+If a language client does not know about `rust-analyzer`'s configuration options it can get sensible defaults by doing any of the following:
+ * Not sending `initializationOptions`
+ * Send `"initializationOptions": null`
+ * Send `"initializationOptions": {}`
 
 ## Snippet `TextEdit`
 
@@ -272,6 +274,11 @@ interface SsrParams {
     query: string,
     /// If true, only check the syntax of the query and don't compute the actual edit.
     parseOnly: bool,
+    /// The current text document. This and `position` will be used to determine in what scope
+    /// paths in `query` should be resolved.
+    textDocument: lc.TextDocumentIdentifier;
+    /// Position where SSR was invoked.
+    position: lc.Position;
 }
 ```
 
@@ -283,7 +290,7 @@ 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)`.
+SSR with query `foo($a, $b) ==>> ($a).foo($b)` will transform, eg `foo(y + 5, z)` into `(y + 5).foo(z)`.
 
 ### Unresolved Question
 
@@ -389,15 +396,27 @@ rust-analyzer supports only one `kind`, `"cargo"`. The `args` for `"cargo"` look
 
 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
 
@@ -504,4 +523,4 @@ Such actions on the client side are appended to a hover bottom as command links:
   | TITLE _Action1_ | _Action2_ |  <- second group
   +-----------------------------+
   ...
-```
\ No newline at end of file
+```
diff --git a/docs/dev/syntax.md b/docs/dev/syntax.md
index c2864bbbc..d4bc4b07c 100644
--- a/docs/dev/syntax.md
+++ b/docs/dev/syntax.md
@@ -82,7 +82,7 @@ Points of note:
 An input like `fn f() { 90 + 2 }` might be parsed as
 
 ```
-FN_DEF@0..17
+[email protected]
   [email protected] "fn"
   [email protected] " "
   [email protected]
@@ -342,7 +342,7 @@ pub struct FnDef {
 impl AstNode for FnDef {
     fn cast(syntax: SyntaxNode) -> Option<Self> {
         match kind {
-            FN_DEF => Some(FnDef { syntax }),
+            FN => Some(FnDef { syntax }),
             _ => None,
         }
     }
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index b763958fe..cfc0ad81c 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.
 
@@ -106,20 +110,8 @@ 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 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.
-
-==== 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].
+* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Rust Analyzer Language Server Trace` in the panel.
+* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open `Output > Rust Analyzer Client` in the panel.
 
 === rust-analyzer Language Server Binary
 
@@ -281,9 +273,6 @@ However, if you use some other build system, you'll have to describe the structu
 [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[];
@@ -296,11 +285,37 @@ interface Crate {
     edition: "2015" | "2018";
     /// Dependencies
     deps: Dep[];
+    /// Should this crate be treated as a member of current "workspace".
+    ///
+    /// By default, inferred from the `root_module` (members are the crates which reside
+    /// inside the directory opened in the editor).
+    ///
+    /// Set this to `false` for things like standard library and 3rd party crates to
+    /// enable performance optimizations (rust-analyzer assumes that non-member crates
+    /// don't change).
+    is_workspace_member?: boolean;
+    /// Optionally specify the (super)set of `.rs` files comprising this crate.
+    ///
+    /// By default, rust-analyzer assumes that only files under `root_module.parent` can belong to a crate.
+    /// `include_dirs` are included recursively, unless a subdirectory is in `exclude_dirs`.
+    ///
+    /// Different crates can share the same `source`.
+    ///
+    /// If two crates share an `.rs` file in common, they *must* have the same `source`.
+    /// rust-analyzer assumes that files from one source can't refer to files in another source.
+    source?: {
+        include_dirs: string[],
+        exclude_dirs: string[],
+    },
     /// The set of cfgs activated for a given crate, like `["unix", "feature=foo", "feature=bar"]`.
     cfg: string[];
+    /// Target triple for this Crate.
+    ///
+    /// Used when running `rustc --print cfg` to get target-specific cfgs.
+    target?: string;
+    /// Environment variables, used for the `env!` macro
+    env: : { [key: string]: 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;
 }
@@ -337,3 +352,66 @@ 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.
+
+==== Compiler feedback from external commands
+
+Instead of relying on the built-in `cargo check`, you can configure Code to run a command in the background and use the `$rustc-watch` problem matcher to generate inline error markers from its output.
+
+To do this you need to create a new https://code.visualstudio.com/docs/editor/tasks[VS Code Task] and set `rust-analyzer.checkOnSave.enable: false` in preferences.
+
+For example, if you want to run https://crates.io/crates/cargo-watch[`cargo watch`] instead, you might add the following to `.vscode/tasks.json`:
+
+```json
+{
+    "label": "Watch",
+    "group": "build",
+    "type": "shell",
+    "command": "cargo watch",
+    "problemMatcher": "$rustc-watch",
+    "isBackground": true
+}
+```