2 files changed, 43 insertions, 28 deletions

diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index cb2ae6fc1..3025dc8d6 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -5,7 +5,7 @@ rust-analyzer.assist.importPrefix (default: `"plain"`)::
 rust-analyzer.callInfo.full (default: `true`)::
  Show function name and docs in parameter hints.
 rust-analyzer.cargo.autoreload (default: `true`)::
- Automatically refresh project info via `cargo metadata` on  Cargo.toml changes.
+ Automatically refresh project info via `cargo metadata` on  `Cargo.toml` changes.
 rust-analyzer.cargo.allFeatures (default: `false`)::
  Activate all available features.
 rust-analyzer.cargo.features (default: `[]`)::
@@ -21,7 +21,7 @@ rust-analyzer.cargo.noSysroot (default: `false`)::
 rust-analyzer.checkOnSave.enable (default: `true`)::
  Run specified `cargo check` command for diagnostics on save.
 rust-analyzer.checkOnSave.allFeatures (default: `null`)::
- Check with all features (will be passed as `--all-features`).  Defaults to `rust-analyzer.cargo.allFeatures`.
+ Check with all features (will be passed as `--all-features`).  Defaults to `#rust-analyzer.cargo.allFeatures#`.
 rust-analyzer.checkOnSave.allTargets (default: `true`)::
  Check all targets and tests (will be passed as `--all-targets`).
 rust-analyzer.checkOnSave.command (default: `"check"`)::
@@ -29,11 +29,11 @@ rust-analyzer.checkOnSave.command (default: `"check"`)::
 rust-analyzer.checkOnSave.noDefaultFeatures (default: `null`)::
  Do not activate the `default` feature.
 rust-analyzer.checkOnSave.target (default: `null`)::
- Check for a specific target. Defaults to  `rust-analyzer.cargo.target`.
+ Check for a specific target. Defaults to  `#rust-analyzer.cargo.target#`.
 rust-analyzer.checkOnSave.extraArgs (default: `[]`)::
  Extra arguments for `cargo check`.
 rust-analyzer.checkOnSave.features (default: `null`)::
- List of features to activate. Defaults to  `rust-analyzer.cargo.features`.
+ List of features to activate. Defaults to  `#rust-analyzer.cargo.features#`.
 rust-analyzer.checkOnSave.overrideCommand (default: `null`)::
  Advanced option, fully override the command rust-analyzer uses for  checking. The command should include `--message-format=json` or  similar option.
 rust-analyzer.completion.addCallArgumentSnippets (default: `true`)::
@@ -43,7 +43,7 @@ rust-analyzer.completion.addCallParenthesis (default: `true`)::
 rust-analyzer.completion.postfix.enable (default: `true`)::
  Whether to show postfix snippets like `dbg`, `if`, `not`, etc.
 rust-analyzer.completion.autoimport.enable (default: `true`)::
- Toggles the additional completions that automatically add imports when completed.  Note that your client have to specify the `additionalTextEdits` LSP client capability to truly have this feature enabled.
+ Toggles the additional completions that automatically add imports when completed.  Note that your client must specify the `additionalTextEdits` LSP client capability to truly have this feature enabled.
 rust-analyzer.diagnostics.enable (default: `true`)::
  Whether to show native rust-analyzer diagnostics.
 rust-analyzer.diagnostics.enableExperimental (default: `true`)::
@@ -51,9 +51,9 @@ rust-analyzer.diagnostics.enableExperimental (default: `true`)::
 rust-analyzer.diagnostics.disabled (default: `[]`)::
  List of rust-analyzer diagnostics to disable.
 rust-analyzer.diagnostics.warningsAsHint (default: `[]`)::
- List of warnings that should be displayed with info severity.\nThe  warnings will be indicated by a blue squiggly underline in code and  a blue icon in the problems panel.
+ List of warnings that should be displayed with info severity.\n\nThe  warnings will be indicated by a blue squiggly underline in code and  a blue icon in the `Problems Panel`.
 rust-analyzer.diagnostics.warningsAsInfo (default: `[]`)::
- List of warnings that should be displayed with hint severity.\nThe  warnings will be indicated by faded text or three dots in code and  will not show up in the problems panel.
+ List of warnings that should be displayed with hint severity.\n\nThe  warnings will be indicated by faded text or three dots in code and  will not show up in the `Problems Panel`.
 rust-analyzer.files.watcher (default: `"client"`)::
  Controls file watching implementation.
 rust-analyzer.hoverActions.debug (default: `true`)::
@@ -71,7 +71,7 @@ rust-analyzer.hoverActions.linksInHover (default: `true`)::
 rust-analyzer.inlayHints.chainingHints (default: `true`)::
  Whether to show inlay type hints for method chains.
 rust-analyzer.inlayHints.maxLength (default: `null`)::
- Maximum length for inlay hints.
+ Maximum length for inlay hints. Default is unlimited.
 rust-analyzer.inlayHints.parameterHints (default: `true`)::
  Whether to show function parameter name inlay hints at the call  site.
 rust-analyzer.inlayHints.typeHints (default: `true`)::
@@ -87,20 +87,20 @@ rust-analyzer.lens.run (default: `true`)::
 rust-analyzer.lens.methodReferences (default: `false`)::
  Whether to show `Method References` lens. Only applies when  `#rust-analyzer.lens.enable#` is set.
 rust-analyzer.linkedProjects (default: `[]`)::
- Disable project auto-discovery in favor of explicitly specified set  of projects.  \nElements must be paths pointing to Cargo.toml,  rust-project.json, or JSON objects in rust-project.json format.
+ Disable project auto-discovery in favor of explicitly specified set  of projects.\n\nElements must be paths pointing to `Cargo.toml`,  `rust-project.json`, or JSON objects in `rust-project.json` format.
 rust-analyzer.lruCapacity (default: `null`)::
- Number of syntax trees rust-analyzer keeps in memory.
+ Number of syntax trees rust-analyzer keeps in memory.  Defaults to 128.
 rust-analyzer.notifications.cargoTomlNotFound (default: `true`)::
  Whether to show `can't find Cargo.toml` error message.
 rust-analyzer.procMacro.enable (default: `false`)::
- Enable Proc macro support, cargo.loadOutDirsFromCheck must be  enabled.
+ Enable Proc macro support, `#rust-analyzer.cargo.loadOutDirsFromCheck#` must be  enabled.
 rust-analyzer.runnables.overrideCargo (default: `null`)::
  Command to be executed instead of 'cargo' for runnables.
 rust-analyzer.runnables.cargoExtraArgs (default: `[]`)::
- Additional arguments to be passed to cargo for runnables such as  tests or binaries.\nFor example, it may be '--release'.
+ Additional arguments to be passed to cargo for runnables such as  tests or binaries.\nFor example, it may be `--release`.
 rust-analyzer.rustcSource (default: `null`)::
  Path to the rust compiler sources, for usage in rustc_private projects.
 rust-analyzer.rustfmt.extraArgs (default: `[]`)::
- Additional arguments to rustfmt.
+ Additional arguments to `rustfmt`.
 rust-analyzer.rustfmt.overrideCommand (default: `null`)::
  Advanced option, fully override the command rust-analyzer uses for  formatting.
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index 1ec6e81bb..e3082d584 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -46,8 +46,8 @@ You can install the latest release of the plugin from
 https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace].
 
 Note that the plugin may cause conflicts with the
-https://marketplace.visualstudio.com/items?itemName=rust-lang.rust[official Rust plugin]. It is
-recommended to disable the Rust plugin when using the rust-analyzer extension.
+https://marketplace.visualstudio.com/items?itemName=rust-lang.rust[official Rust plugin].
+It is recommended to disable the Rust plugin when using the rust-analyzer extension.
 
 By default, the plugin will prompt you to download the matching version of the server as well:
 
@@ -74,18 +74,21 @@ Note that we only support two most recent versions of VS Code.
 
 ==== Updates
 
-The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed.
+The extension will be updated automatically as new versions become available.
+It will ask your permission to download the matching language server version binary if needed.
 
 ===== Nightly
 
-We ship nightly releases for VS Code. To help us out with testing the newest code and follow the bleeding edge of our `master`, please use the following config:
+We ship nightly releases for VS Code.
+To help us out with testing the newest code and follow the bleeding edge of our `master`, please use the following config:
 
 [source,json]
 ----
 { "rust-analyzer.updates.channel": "nightly" }
 ----
 
-You will be prompted to install the `nightly` extension version. Just click `Download now` and from that moment you will get automatic updates every 24 hours.
+You will be prompted to install the `nightly` extension version.
+Just click `Download now` and from that moment you will get automatic updates every 24 hours.
 
 If you don't want to be asked for `Download now` every day when the new nightly version is released add the following to your `settings.json`:
 [source,json]
@@ -160,7 +163,8 @@ $ chmod +x ~/.local/bin/rust-analyzer
 
 Ensure `~/.local/bin` is listed in the `$PATH` variable.
 
-Alternatively, you can install it from source using the following command:
+Alternatively, you can install it from source using the command below.
+You'll need the latest stable version of the Rust toolchain.
 
 [source,bash]
 ----
@@ -198,7 +202,8 @@ Emacs support is maintained as part of the https://github.com/emacs-lsp/lsp-mode
 
 === Vim/NeoVim
 
-Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>. Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example.
+Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
+Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example.
 
 The are several LSP client implementations for vim or neovim:
 
@@ -270,14 +275,16 @@ Once `neovim/nvim-lspconfig` is installed, use `+lua require'nvim_lsp'.rust_anal
 
 Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
 
-You also need the `LSP` package. To install it:
+You also need the `LSP` package.
+To install it:
 
 1. If you've never installed a Sublime Text package, install Package Control:
    * Open the command palette (Win/Linux: `ctrl+shift+p`, Mac: `cmd+shift+p`)
    * Type `Install Package Control`, press enter
 2. In the command palette, run `Package control: Install package`, and in the list that pops up, type `LSP` and press enter.
 
-Finally, with your Rust project open, in the command palette, run `LSP: Enable Language Server In Project` or `LSP: Enable Language Server Globally`, then select `rust-analyzer` in the list that pops up to enable the rust-analyzer LSP. The latter means that rust-analyzer is enabled by default in Rust projects.
+Finally, with your Rust project open, in the command palette, run `LSP: Enable Language Server In Project` or `LSP: Enable Language Server Globally`, then select `rust-analyzer` in the list that pops up to enable the rust-analyzer LSP.
+The latter means that rust-analyzer is enabled by default in Rust projects.
 
 If it worked, you should see "rust-analyzer, Line X, Column Y" on the left side of the bottom bar, and after waiting a bit, functionality like tooltips on hovering over variables should become available.
 
@@ -285,7 +292,8 @@ If you get an error saying `No such file or directory: 'rust-analyzer'`, see the
 
 === GNOME Builder
 
-GNOME Builder 3.37.1 and newer has native `rust-analyzer` support. If the LSP binary is not available, GNOME Builder can install it when opening a Rust file.
+GNOME Builder 3.37.1 and newer has native `rust-analyzer` support.
+If the LSP binary is not available, GNOME Builder can install it when opening a Rust file.
 
 == Configuration
 
@@ -294,6 +302,9 @@ GNOME Builder 3.37.1 and newer has native `rust-analyzer` support. If the LSP bi
 rust-analyzer is configured via LSP messages, which means that it's up to the editor to decide on the exact format and location of configuration files.
 Please consult your editor's documentation to learn how to configure LSP servers.
 
+To verify which configuration is actually used by rust-analyzer, set `RA_LOG` environment variable to `rust_analyzer=info` and look for config-related messages.
+Logs should show both the JSON that rust-analyzer sees as well as the updated config.
+
 This is the list of config options rust-analyzer supports:
 
 include::./generated_config.adoc[]
@@ -413,8 +424,8 @@ include::./generated_diagnostic.adoc[]
 
 ==== Color configurations
 
-It is possible to change the foreground/background color of inlay hints. Just add this to your
-`settings.json`:
+It is possible to change the foreground/background color of inlay hints.
+Just add this to your `settings.json`:
 
 [source,jsonc]
 ----
@@ -436,7 +447,8 @@ It is possible to change the foreground/background color of inlay hints. Just ad
 
 ==== Semantic style customizations
 
-You can customize the look of different semantic elements in the source code. For example, mutable bindings are underlined by default and you can override this behavior by adding the following section to your `settings.json`:
+You can customize the look of different semantic elements in the source code.
+For example, mutable bindings are underlined by default and you can override this behavior by adding the following section to your `settings.json`:
 
 [source,jsonc]
 ----
@@ -452,7 +464,9 @@ You can customize the look of different semantic elements in the source code. Fo
 ----
 
 ==== Special `when` clause context for keybindings.
-You may use `inRustProject` context to configure keybindings for rust projects only. For example:
+You may use `inRustProject` context to configure keybindings for rust projects only.
+For example:
+
 [source,json]
 ----
 {
@@ -491,7 +505,8 @@ Or it is possible to specify vars more granularly:
 ]
 ```
 
-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.
+You can use any valid regular expression 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