4 files changed, 44 insertions, 17 deletions

diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
index 39edf9e19..3de1b99a5 100644
--- a/docs/dev/architecture.md
+++ b/docs/dev/architecture.md
@@ -146,6 +146,8 @@ Reading the docs of the `base_db::input` module should be useful: everything els
 
 **Architecture Invariant:** particularities of the build system are *not* the part of the ground state.
 In particular, `base_db` knows nothing about cargo.
+For example, `cfg` flags are a part of `base_db`, but `feature`s are not.
+A `foo` feature is a Cargo-level concept, which is lowered by Cargo to `--cfg feature=foo` argument on the command line.
 The `CrateGraph` structure is used to represent the dependencies between the crates abstractly.
 
 **Architecture Invariant:** `base_db` doesn't know about file system and file paths.
@@ -447,3 +449,9 @@ This is cheap enough to enable in production.
 
 Similarly, we save live object counting (`RA_COUNT=1`).
 It is not cheap enough to enable in prod, and this is a bug which should be fixed.
+
+### Configurability
+
+rust-analyzer strives to be as configurable as possible while offering reasonable defaults where no configuration exists yet.
+There will always be features that some people find more annoying than helpful, so giving the users the ability to tweak or disable these is a big part of offering a good user experience.
+Mind the code--architecture gap: at the moment, we are using fewer feature flags than we really should.
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index fbe2ce1c9..11a3dd04e 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -25,15 +25,21 @@ rust-analyzer supports clangd's extension for opting into UTF-8 as the coordinat
 
 https://clangd.llvm.org/extensions.html#utf-8-offsets
 
-## `initializationOptions`
+## Configuration in `initializationOptions`
+
+**Issue:** https://github.com/microsoft/language-server-protocol/issues/567
+
+The `initializationOptions` filed of the `InitializeParams` of the initialization request should contain `"rust-analyzer"` section of the configuration.
+
+`rust-analyzer` normally sends a `"workspace/configuration"` request with `{ "items": ["rust-analyzer"] }` payload.
+However, the server can't do this during initialization.
+At the same time some essential configuration parameters are needed early on, before servicing requests.
+For this reason, we ask that `initializationOptions` contains the configuration, as if the server did make a `"workspace/configuration"` request.
 
-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.
 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": {}`
+ * Sending `"initializationOptions": null`
+ * Sending `"initializationOptions": {}`
 
 ## Snippet `TextEdit`
 
diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index c02bab7cc..dbd9a3503 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -136,6 +136,12 @@ Whether to show postfix snippets like `dbg`, `if`, `not`, etc.
 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.completion.autoself.enable]]rust-analyzer.completion.autoself.enable (default: `true`)::
++
+--
+Toggles the additional completions that automatically show method calls and field accesses
+with `self` prefixed to them when inside a method.
+--
 [[rust-analyzer.diagnostics.enable]]rust-analyzer.diagnostics.enable (default: `true`)::
 +
 --
@@ -161,18 +167,18 @@ This should be the reverse mapping of what is passed to `rustc` as `--remap-path
 [[rust-analyzer.diagnostics.warningsAsHint]]rust-analyzer.diagnostics.warningsAsHint (default: `[]`)::
 +
 --
-List of warnings that should be displayed with info severity.
+List of warnings that should be displayed with hint severity.
 
-The warnings will be indicated by a blue squiggly underline in code
-and a blue icon in the `Problems Panel`.
+The warnings will be indicated by faded text or three dots in code
+and will not show up in the `Problems Panel`.
 --
 [[rust-analyzer.diagnostics.warningsAsInfo]]rust-analyzer.diagnostics.warningsAsInfo (default: `[]`)::
 +
 --
-List of warnings that should be displayed with hint severity.
+List of warnings that should be displayed with info severity.
 
-The warnings will be indicated by faded text or three dots in code
-and will not show up in the `Problems Panel`.
+The warnings will be indicated by a blue squiggly underline in code
+and a blue icon in the `Problems Panel`.
 --
 [[rust-analyzer.files.watcher]]rust-analyzer.files.watcher (default: `"client"`)::
 +
@@ -346,6 +352,13 @@ Additional arguments to `rustfmt`.
 Advanced option, fully override the command rust-analyzer uses for
 formatting.
 --
+[[rust-analyzer.rustfmt.enableRangeFormatting]]rust-analyzer.rustfmt.enableRangeFormatting (default: `false`)::
++
+--
+Enables the use of rustfmt's unstable range formatting command for the
+`textDocument/rangeFormatting` request. The rustfmt option is unstable and only
+available on a nightly build.
+--
 [[rust-analyzer.workspace.symbol.search.scope]]rust-analyzer.workspace.symbol.search.scope (default: `"workspace"`)::
 +
 --
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index ad367511b..1f95df56e 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -139,18 +139,18 @@ $ cargo xtask install --server
 === 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 pre-built binaries from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page.
+You will need to uncompress and rename the binary for your platform, e.g. from `rust-analyzer-aarch64-apple-darwin.gz` on Mac OS to `rust-analyzer`, make it executable, then move it into a directory in your `$PATH`.
 
-On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used
+On Linux to install the `rust-analyzer` binary into `~/.local/bin`, these commands should work:
 
 [source,bash]
 ----
-$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-linux -o ~/.local/bin/rust-analyzer
+$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-x86_64-unknown-linux-gnu.gz | gunzip -c - > ~/.local/bin/rust-analyzer
 $ chmod +x ~/.local/bin/rust-analyzer
 ----
 
-Ensure `~/.local/bin` is listed in the `$PATH` variable.
+Make sure that `~/.local/bin` is listed in the `$PATH` variable and use the appropriate URL if you're not on a `x86-64` system.
 
 Alternatively, you can install it from source using the command below.
 You'll need the latest stable version of the Rust toolchain.