2 files changed, 227 insertions, 178 deletions

diff --git a/docs/dev/style.md b/docs/dev/style.md
index fb407afcd..59067d234 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -6,7 +6,9 @@ Our approach to "clean code" is two-fold:
 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
+# General
+
+## 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.
@@ -45,13 +47,35 @@ That said, adding an innocent-looking `pub use` is a very simple way to break en
 Note: if you enjoyed this abstract hand-waving about boundaries, you might appreciate
 https://www.tedinski.com/2018/02/06/system-boundaries.html
 
-# Crates.io Dependencies
+## Crates.io Dependencies
 
 We try to be very conservative with usage of crates.io dependencies.
 Don't use small "helper" crates (exception: `itertools` is allowed).
 If there's some general reusable bit of code you need, consider adding it to the `stdx` crate.
 
-# Minimal Tests
+## Commit Style
+
+We don't have specific rules around git history hygiene.
+Maintaining clean git history is strongly encouraged, but not enforced.
+Use rebase workflow, it's OK to rewrite history during PR review process.
+After you are happy with the state of the code, please use [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to squash fixup commits.
+
+Avoid @mentioning people in commit messages and pull request descriptions(they are added to commit message by bors).
+Such messages create a lot of duplicate notification traffic during rebases.
+
+## Clippy
+
+We don't enforce Clippy.
+A number of default lints have high false positive rate.
+Selectively patching false-positives with `allow(clippy)` is considered worse than not using Clippy at all.
+There's `cargo xtask lint` command which runs a subset of low-FPR lints.
+Careful tweaking of `xtask lint` is welcome.
+See also [rust-lang/clippy#5537](https://github.com/rust-lang/rust-clippy/issues/5537).
+Of course, applying Clippy suggestions is welcome as long as they indeed improve the code.
+
+# Code
+
+## 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.
@@ -65,119 +89,7 @@ There are many benefits to this:
 It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line),
 as long as they are still readable.
 
-# Order of Imports
-
-Separate import groups with blank lines.
-Use one `use` per crate.
-
-```rust
-mod x;
-mod y;
-
-// First std.
-use std::{ ... }
-
-// Second, external crates (both crates.io crates and other rust-analyzer crates).
-use crate_foo::{ ... }
-use crate_bar::{ ... }
-
-// Then current crate.
-use crate::{}
-
-// Finally, parent and child modules, but prefer `use crate::`.
-use super::{}
-```
-
-Module declarations come before the imports.
-Order them in "suggested reading order" for a person new to the code base.
-
-# Import Style
-
-Qualify items from `hir` and `ast`.
-
-```rust
-// Good
-use syntax::ast;
-
-fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
-
-// Not as good
-use hir::Function;
-use syntax::ast::StructDef;
-
-fn frobnicate(func: Function, strukt: StructDef) {}
-```
-
-Avoid local `use MyEnum::*` imports.
-
-Prefer `use crate::foo::bar` to `use super::bar`.
-
-When implementing `Debug` or `Display`, import `std::fmt`:
-
-```rust
-// Good
-use std::fmt;
-
-impl fmt::Display for RenameError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { .. }
-}
-
-// Not as good
-impl std::fmt::Display for RenameError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { .. }
-}
-```
-
-# Order of Items
-
-Optimize for the reader who sees the file for the first time, and wants to get a 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
-
-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`).
-
-Default names:
-
-* `res` -- "result of the function" local variable
-* `it` -- I don't really care about the name
-* `n_foo` -- number of foos
-* `foo_idx` -- index of `foo`
-
-# Collection types
-
-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
+## Preconditions
 
 Express function preconditions in types and force the caller to provide them (rather than checking in callee):
 
@@ -199,9 +111,15 @@ fn frobnicate(walrus: Option<Walrus>) {
 
 Avoid preconditions that span across function boundaries:
 
-
 ```rust
 // Good
+fn main() {
+    let s: &str = ...;
+    if let Some(contents) = string_literal_contents(s) {
+
+    }
+}
+
 fn string_literal_contents(s: &str) -> Option<&str> {
     if s.starts_with('"') && s.ends_with('"') {
         Some(&s[1..s.len() - 1])
@@ -210,54 +128,37 @@ fn string_literal_contents(s: &str) -> Option<&str> {
     }
 }
 
-fn foo() {
+// Not as good
+fn main() {
     let s: &str = ...;
-    if let Some(contents) = string_literal_contents(s) {
-
+    if is_string_literal(s) {
+        let contents = &s[1..s.len() - 1];
     }
 }
 
-// Not as good
 fn is_string_literal(s: &str) -> bool {
     s.starts_with('"') && s.ends_with('"')
 }
-
-fn foo() {
-    let s: &str = ...;
-    if is_string_literal(s) {
-        let contents = &s[1..s.len() - 1];
-    }
-}
 ```
 
 In the "Not as good" version, the precondition that `1` is a valid char boundary is checked in `is_string_literal` and used in `foo`.
 In the "Good" version, the precondition check and usage are checked in the same block, and then encoded in the types.
 
-# Early Returns
-
-Do use early returns
+When checking a boolean precondition, prefer `if !invariant` to `if negated_invariant`:
 
 ```rust
 // Good
-fn foo() -> Option<Bar> {
-    if !condition() {
-        return None;
-    }
-
-    Some(...)
+if !(idx < len) {
+    return None;
 }
 
 // Not as good
-fn foo() -> Option<Bar> {
-    if condition() {
-        Some(...)
-    } else {
-        None
-    }
+if idx >= len {
+    return None;
 }
 ```
 
-# Getters & Setters
+## Getters & Setters
 
 If a field can have any value without breaking invariants, make the field public.
 Conversely, if there is an invariant, document it, enforce it in the "constructor" function, make the field private, and provide a getter.
@@ -285,6 +186,40 @@ impl Person {
 }
 ```
 
+## Avoid Monomorphization
+
+Rust uses monomorphization to compile generic code, meaning that for each instantiation of a generic functions with concrete types, the function is compiled afresh, *per crate*.
+This allows for exceptionally good performance, but leads to increased compile times.
+Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot.
+Compile time **does not** obey this rule -- all code has to be compiled.
+For this reason, avoid making a lot of code type parametric, *especially* on the boundaries between crates.
+
+```rust
+// Good
+fn frbonicate(f: impl FnMut()) {
+    frobnicate_impl(&mut f)
+}
+fn frobnicate_impl(f: &mut dyn FnMut()) {
+    // lots of code
+}
+
+// Not as good
+fn frbonicate(f: impl FnMut()) {
+    // lots of code
+}
+```
+
+Avoid `AsRef` polymorphism, it pays back only for widely used libraries:
+
+```rust
+// Good
+fn frbonicate(f: &Path) {
+}
+
+// Not as good
+fn frbonicate(f: impl AsRef<Path>) {
+}
+```
 
 # Premature Pessimization
 
@@ -322,62 +257,159 @@ fn frobnicate(s: &str) {
 }
 ```
 
-# Avoid Monomorphization
+## Collection types
 
-Rust uses monomorphization to compile generic code, meaning that for each instantiation of a generic functions with concrete types, the function is compiled afresh, *per crate*.
-This allows for exceptionally good performance, but leads to increased compile times.
-Runtime performance obeys 80%/20% rule -- only a small fraction of code is hot.
-Compile time **does not** obey this rule -- all code has to be compiled.
-For this reason, avoid making a lot of code type parametric, *especially* on the boundaries between crates.
+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.
+
+# Style
+
+## Order of Imports
+
+Separate import groups with blank lines.
+Use one `use` per crate.
+
+```rust
+mod x;
+mod y;
+
+// First std.
+use std::{ ... }
+
+// Second, external crates (both crates.io crates and other rust-analyzer crates).
+use crate_foo::{ ... }
+use crate_bar::{ ... }
+
+// Then current crate.
+use crate::{}
+
+// Finally, parent and child modules, but prefer `use crate::`.
+use super::{}
+```
+
+Module declarations come before the imports.
+Order them in "suggested reading order" for a person new to the code base.
+
+## Import Style
+
+Qualify items from `hir` and `ast`.
 
 ```rust
 // Good
-fn frbonicate(f: impl FnMut()) {
-    frobnicate_impl(&mut f)
-}
-fn frobnicate_impl(f: &mut dyn FnMut()) {
-    // lots of code
+use syntax::ast;
+
+fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
+
+// Not as good
+use hir::Function;
+use syntax::ast::StructDef;
+
+fn frobnicate(func: Function, strukt: StructDef) {}
+```
+
+Avoid local `use MyEnum::*` imports.
+
+Prefer `use crate::foo::bar` to `use super::bar`.
+
+When implementing `Debug` or `Display`, import `std::fmt`:
+
+```rust
+// Good
+use std::fmt;
+
+impl fmt::Display for RenameError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { .. }
 }
 
 // Not as good
-fn frbonicate(f: impl FnMut()) {
-    // lots of code
+impl std::fmt::Display for RenameError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { .. }
 }
 ```
 
-Avoid `AsRef` polymorphism, it pays back only for widely used libraries:
+## Order of Items
+
+Optimize for the reader who sees the file for the first time, and wants to get a 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
-fn frbonicate(f: &Path) {
+struct Foo {
+    bars: Vec<Bar>
 }
 
+struct Bar;
+```
+
+rather than
+
+```rust
 // Not as good
-fn frbonicate(f: impl AsRef<Path>) {
+struct Bar;
+
+struct Foo {
+    bars: Vec<Bar>
 }
 ```
 
-# Documentation
+## Variable Naming
 
-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 :-)
+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`).
 
-# Commit Style
+Default names:
 
-We don't have specific rules around git history hygiene.
-Maintaining clean git history is strongly encouraged, but not enforced.
-Use rebase workflow, it's OK to rewrite history during PR review process.
-After you are happy with the state of the code, please use [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) to squash fixup commits.
+* `res` -- "result of the function" local variable
+* `it` -- I don't really care about the name
+* `n_foo` -- number of foos
+* `foo_idx` -- index of `foo`
 
-Avoid @mentioning people in commit messages and pull request descriptions(they are added to commit message by bors).
-Such messages create a lot of duplicate notification traffic during rebases.
 
-# Clippy
+## Early Returns
 
-We don't enforce Clippy.
-A number of default lints have high false positive rate.
-Selectively patching false-positives with `allow(clippy)` is considered worse than not using Clippy at all.
-There's `cargo xtask lint` command which runs a subset of low-FPR lints.
-Careful tweaking of `xtask lint` is welcome.
-See also [rust-lang/clippy#5537](https://github.com/rust-lang/rust-clippy/issues/5537).
-Of course, applying Clippy suggestions is welcome as long as they indeed improve the code.
+Do use early returns
+
+```rust
+// Good
+fn foo() -> Option<Bar> {
+    if !condition() {
+        return None;
+    }
+
+    Some(...)
+}
+
+// Not as good
+fn foo() -> Option<Bar> {
+    if condition() {
+        Some(...)
+    } else {
+        None
+    }
+}
+```
+
+## Comparisons
+
+Use `<`/`<=`, avoid `>`/`>=`.
+Less-then comparisons are more intuitive, they correspond spatially to [real line](https://en.wikipedia.org/wiki/Real_line)
+
+```rust
+// Good
+assert!(lo <= x && x <= hi);
+
+// Not as good
+assert!(x >= lo && x <= hi>);
+```
+
+## 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 :-)
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index c1a778852..46e7bd091 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -397,6 +397,23 @@ 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`:
+
+[source,jsonc]
+----
+{
+  "editor.semanticTokenColorCustomizations": {
+    "rules": {
+      "*.mutable": {
+        "fontStyle": "", // underline is the default
+      },
+    }
+  },
+}
+----
+
 ==== Special `when` clause context for keybindings.
 You may use `inRustProject` context to configure keybindings for rust projects only. For example:
 [source,json]