11 files changed, 217 insertions, 129 deletions

diff --git a/README.md b/README.md
index 1e7c3e9b4..7ba705e73 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ Work on rust-analyzer is sponsored by
 
 [<img src="https://user-images.githubusercontent.com/1711539/58105231-cf306900-7bee-11e9-83d8-9f1102e59d29.png" alt="Ferrous Systems" width="300">](https://ferrous-systems.com/)
 - [Mozilla](https://www.mozilla.org/en-US/)
+- [Embark Studios](https://embark-studios.com/)
 - [freiheit.com](https://www.freiheit.com)
 
 ## Quick Start
diff --git a/crates/ra_assists/src/ast_transform.rs b/crates/ra_assists/src/ast_transform.rs
index 3079a02a2..00fa95b6c 100644
--- a/crates/ra_assists/src/ast_transform.rs
+++ b/crates/ra_assists/src/ast_transform.rs
@@ -106,6 +106,7 @@ impl<'a> SubstituteTypeParams<'a> {
             _ => return None,
         };
         // FIXME: use `hir::Path::from_src` instead.
+        #[allow(deprecated)]
         let path = hir::Path::from_ast(path)?;
         let resolution = self.source_scope.resolve_hir_path(&path)?;
         match resolution {
@@ -150,6 +151,7 @@ impl<'a> QualifyPaths<'a> {
             return None;
         }
         // FIXME: use `hir::Path::from_src` instead.
+        #[allow(deprecated)]
         let hir_path = hir::Path::from_ast(p.clone());
         let resolution = self.source_scope.resolve_hir_path(&hir_path?)?;
         match resolution {
diff --git a/crates/ra_assists/src/handlers/fill_match_arms.rs b/crates/ra_assists/src/handlers/fill_match_arms.rs
index cc303285b..569efb768 100644
--- a/crates/ra_assists/src/handlers/fill_match_arms.rs
+++ b/crates/ra_assists/src/handlers/fill_match_arms.rs
@@ -136,8 +136,20 @@ fn is_variant_missing(existing_arms: &mut Vec<MatchArm>, var: &Pat) -> bool {
 }
 
 fn does_pat_match_variant(pat: &Pat, var: &Pat) -> bool {
-    let pat_head = pat.syntax().first_child().map(|node| node.text());
-    let var_head = var.syntax().first_child().map(|node| node.text());
+    let first_node_text = |pat: &Pat| pat.syntax().first_child().map(|node| node.text());
+
+    let pat_head = match pat {
+        Pat::BindPat(bind_pat) => {
+            if let Some(p) = bind_pat.pat() {
+                first_node_text(&p)
+            } else {
+                return false;
+            }
+        }
+        pat => first_node_text(pat),
+    };
+
+    let var_head = first_node_text(var);
 
     pat_head == var_head
 }
@@ -351,6 +363,40 @@ mod tests {
     }
 
     #[test]
+    fn partial_fill_bind_pat() {
+        check_assist(
+            fill_match_arms,
+            r#"
+            enum A {
+                As,
+                Bs,
+                Cs(Option<i32>),
+            }
+            fn main() {
+                match A::As<|> {
+                    A::As(_) => {}
+                    a @ A::Bs(_) => {}
+                }
+            }
+            "#,
+            r#"
+            enum A {
+                As,
+                Bs,
+                Cs(Option<i32>),
+            }
+            fn main() {
+                match A::As {
+                    A::As(_) => {}
+                    a @ A::Bs(_) => {}
+                    $0A::Cs(_) => {}
+                }
+            }
+            "#,
+        );
+    }
+
+    #[test]
     fn fill_match_arms_empty_body() {
         check_assist(
             fill_match_arms,
diff --git a/crates/ra_hir_def/src/path.rs b/crates/ra_hir_def/src/path.rs
index ba16442bd..190d6d98d 100644
--- a/crates/ra_hir_def/src/path.rs
+++ b/crates/ra_hir_def/src/path.rs
@@ -154,7 +154,7 @@ pub enum GenericArg {
 
 impl Path {
     /// Converts an `ast::Path` to `Path`. Works with use trees.
-    /// DEPRECATED: It does not handle `$crate` from macro call.
+    #[deprecated = "Doesn't handle hygiene, don't add new calls, remove old ones"]
     pub fn from_ast(path: ast::Path) -> Option<Path> {
         lower::lower_path(path, &Hygiene::new_unhygienic())
     }
diff --git a/crates/ra_hir_ty/src/_match.rs b/crates/ra_hir_ty/src/_match.rs
index 3e6e1e333..fff257193 100644
--- a/crates/ra_hir_ty/src/_match.rs
+++ b/crates/ra_hir_ty/src/_match.rs
@@ -8,11 +8,11 @@
 //! This file includes the logic for exhaustiveness and usefulness checking for
 //! pattern-matching. Specifically, given a list of patterns for a type, we can
 //! tell whether:
-//! (a) the patterns cover every possible constructor for the type [exhaustiveness]
-//! (b) each pattern is necessary [usefulness]
+//! - (a) the patterns cover every possible constructor for the type (exhaustiveness).
+//! - (b) each pattern is necessary (usefulness).
 //!
-//! The algorithm implemented here is a modified version of the one described in:
-//! http://moscova.inria.fr/~maranget/papers/warn/index.html
+//! The algorithm implemented here is a modified version of the one described in
+//! <http://moscova.inria.fr/~maranget/papers/warn/index.html>.
 //! However, to save future implementors from reading the original paper, we
 //! summarise the algorithm here to hopefully save time and be a little clearer
 //! (without being so rigorous).
@@ -37,20 +37,26 @@
 //! new pattern `p`.
 //!
 //! For example, say we have the following:
+//!
+//! ```ignore
+//! // x: (Option<bool>, Result<()>)
+//! match x {
+//!     (Some(true), _) => {}
+//!     (None, Err(())) => {}
+//!     (None, Err(_)) => {}
+//! }
 //! ```
-//!     // x: (Option<bool>, Result<()>)
-//!     match x {
-//!         (Some(true), _) => {}
-//!         (None, Err(())) => {}
-//!         (None, Err(_)) => {}
-//!     }
-//! ```
+//!
 //! Here, the matrix `P` starts as:
+//!
+//! ```text
 //! [
 //!     [(Some(true), _)],
 //!     [(None, Err(()))],
 //!     [(None, Err(_))],
 //! ]
+//! ```
+//!
 //! We can tell it's not exhaustive, because `U(P, _)` is true (we're not covering
 //! `[(Some(false), _)]`, for instance). In addition, row 3 is not useful, because
 //! all the values it covers are already covered by row 2.
@@ -60,53 +66,61 @@
 //! To match the paper, the top of the stack is at the beginning / on the left.
 //!
 //! There are two important operations on pattern-stacks necessary to understand the algorithm:
-//!     1. We can pop a given constructor off the top of a stack. This operation is called
-//!        `specialize`, and is denoted `S(c, p)` where `c` is a constructor (like `Some` or
-//!        `None`) and `p` a pattern-stack.
-//!        If the pattern on top of the stack can cover `c`, this removes the constructor and
-//!        pushes its arguments onto the stack. It also expands OR-patterns into distinct patterns.
-//!        Otherwise the pattern-stack is discarded.
-//!        This essentially filters those pattern-stacks whose top covers the constructor `c` and
-//!        discards the others.
 //!
-//!        For example, the first pattern above initially gives a stack `[(Some(true), _)]`. If we
-//!        pop the tuple constructor, we are left with `[Some(true), _]`, and if we then pop the
-//!        `Some` constructor we get `[true, _]`. If we had popped `None` instead, we would get
-//!        nothing back.
+//! 1. We can pop a given constructor off the top of a stack. This operation is called
+//!    `specialize`, and is denoted `S(c, p)` where `c` is a constructor (like `Some` or
+//!    `None`) and `p` a pattern-stack.
+//!    If the pattern on top of the stack can cover `c`, this removes the constructor and
+//!    pushes its arguments onto the stack. It also expands OR-patterns into distinct patterns.
+//!    Otherwise the pattern-stack is discarded.
+//!    This essentially filters those pattern-stacks whose top covers the constructor `c` and
+//!    discards the others.
+//!
+//!    For example, the first pattern above initially gives a stack `[(Some(true), _)]`. If we
+//!    pop the tuple constructor, we are left with `[Some(true), _]`, and if we then pop the
+//!    `Some` constructor we get `[true, _]`. If we had popped `None` instead, we would get
+//!    nothing back.
+//!
+//!    This returns zero or more new pattern-stacks, as follows. We look at the pattern `p_1`
+//!    on top of the stack, and we have four cases:
+//!
+//!    * 1.1. `p_1 = c(r_1, .., r_a)`, i.e. the top of the stack has constructor `c`. We push onto
+//!           the stack the arguments of this constructor, and return the result:
+//!
+//!          r_1, .., r_a, p_2, .., p_n
+//!
+//!    * 1.2. `p_1 = c'(r_1, .., r_a')` where `c ≠ c'`. We discard the current stack and return
+//!           nothing.
+//!    * 1.3. `p_1 = _`. We push onto the stack as many wildcards as the constructor `c` has
+//!           arguments (its arity), and return the resulting stack:
 //!
-//!        This returns zero or more new pattern-stacks, as follows. We look at the pattern `p_1`
-//!        on top of the stack, and we have four cases:
-//!             1.1. `p_1 = c(r_1, .., r_a)`, i.e. the top of the stack has constructor `c`. We
-//!                  push onto the stack the arguments of this constructor, and return the result:
-//!                     r_1, .., r_a, p_2, .., p_n
-//!             1.2. `p_1 = c'(r_1, .., r_a')` where `c ≠ c'`. We discard the current stack and
-//!                  return nothing.
-//!             1.3. `p_1 = _`. We push onto the stack as many wildcards as the constructor `c` has
-//!                  arguments (its arity), and return the resulting stack:
-//!                     _, .., _, p_2, .., p_n
-//!             1.4. `p_1 = r_1 | r_2`. We expand the OR-pattern and then recurse on each resulting
-//!                  stack:
-//!                     S(c, (r_1, p_2, .., p_n))
-//!                     S(c, (r_2, p_2, .., p_n))
+//!          _, .., _, p_2, .., p_n
 //!
-//!     2. We can pop a wildcard off the top of the stack. This is called `D(p)`, where `p` is
-//!        a pattern-stack.
-//!        This is used when we know there are missing constructor cases, but there might be
-//!        existing wildcard patterns, so to check the usefulness of the matrix, we have to check
-//!        all its *other* components.
+//!    * 1.4. `p_1 = r_1 | r_2`. We expand the OR-pattern and then recurse on each resulting stack:
 //!
-//!        It is computed as follows. We look at the pattern `p_1` on top of the stack,
-//!        and we have three cases:
-//!             1.1. `p_1 = c(r_1, .., r_a)`. We discard the current stack and return nothing.
-//!             1.2. `p_1 = _`. We return the rest of the stack:
-//!                     p_2, .., p_n
-//!             1.3. `p_1 = r_1 | r_2`. We expand the OR-pattern and then recurse on each resulting
-//!               stack.
-//!                     D((r_1, p_2, .., p_n))
-//!                     D((r_2, p_2, .., p_n))
+//!          S(c, (r_1, p_2, .., p_n))
+//!          S(c, (r_2, p_2, .., p_n))
 //!
-//!     Note that the OR-patterns are not always used directly in Rust, but are used to derive the
-//!     exhaustive integer matching rules, so they're written here for posterity.
+//! 2. We can pop a wildcard off the top of the stack. This is called `D(p)`, where `p` is
+//!    a pattern-stack.
+//!    This is used when we know there are missing constructor cases, but there might be
+//!    existing wildcard patterns, so to check the usefulness of the matrix, we have to check
+//!    all its *other* components.
+//!
+//!    It is computed as follows. We look at the pattern `p_1` on top of the stack,
+//!    and we have three cases:
+//!    * 1.1. `p_1 = c(r_1, .., r_a)`. We discard the current stack and return nothing.
+//!    * 1.2. `p_1 = _`. We return the rest of the stack:
+//!
+//!          p_2, .., p_n
+//!
+//!    * 1.3. `p_1 = r_1 | r_2`. We expand the OR-pattern and then recurse on each resulting stack:
+//!
+//!          D((r_1, p_2, .., p_n))
+//!          D((r_2, p_2, .., p_n))
+//!
+//!    Note that the OR-patterns are not always used directly in Rust, but are used to derive the
+//!    exhaustive integer matching rules, so they're written here for posterity.
 //!
 //! Both those operations extend straightforwardly to a list or pattern-stacks, i.e. a matrix, by
 //! working row-by-row. Popping a constructor ends up keeping only the matrix rows that start with
@@ -120,73 +134,88 @@
 //! operates principally on the first component of the matrix and new pattern-stack `p`.
 //! This algorithm is realised in the `is_useful` function.
 //!
-//! Base case. (`n = 0`, i.e., an empty tuple pattern)
-//!     - If `P` already contains an empty pattern (i.e., if the number of patterns `m > 0`),
-//!       then `U(P, p)` is false.
-//!     - Otherwise, `P` must be empty, so `U(P, p)` is true.
+//! Base case (`n = 0`, i.e., an empty tuple pattern):
+//! - If `P` already contains an empty pattern (i.e., if the number of patterns `m > 0`), then
+//!   `U(P, p)` is false.
+//! - Otherwise, `P` must be empty, so `U(P, p)` is true.
+//!
+//! Inductive step (`n > 0`, i.e., whether there's at least one column [which may then be expanded
+//! into further columns later]). We're going to match on the top of the new pattern-stack, `p_1`:
+//!
+//! - If `p_1 == c(r_1, .., r_a)`, i.e. we have a constructor pattern.
+//!   Then, the usefulness of `p_1` can be reduced to whether it is useful when
+//!   we ignore all the patterns in the first column of `P` that involve other constructors.
+//!   This is where `S(c, P)` comes in:
+//!
+//!   ```text
+//!   U(P, p) := U(S(c, P), S(c, p))
+//!   ```
+//!
+//!   This special case is handled in `is_useful_specialized`.
+//!
+//!   For example, if `P` is:
+//!
+//!   ```text
+//!   [
+//!       [Some(true), _],
+//!       [None, 0],
+//!   ]
+//!   ```
 //!
-//! Inductive step. (`n > 0`, i.e., whether there's at least one column
-//!                  [which may then be expanded into further columns later])
-//!     We're going to match on the top of the new pattern-stack, `p_1`.
-//!         - If `p_1 == c(r_1, .., r_a)`, i.e. we have a constructor pattern.
-//!           Then, the usefulness of `p_1` can be reduced to whether it is useful when
-//!           we ignore all the patterns in the first column of `P` that involve other constructors.
-//!           This is where `S(c, P)` comes in:
-//!           `U(P, p) := U(S(c, P), S(c, p))`
-//!           This special case is handled in `is_useful_specialized`.
+//!   and `p` is `[Some(false), 0]`, then we don't care about row 2 since we know `p` only
+//!   matches values that row 2 doesn't. For row 1 however, we need to dig into the
+//!   arguments of `Some` to know whether some new value is covered. So we compute
+//!   `U([[true, _]], [false, 0])`.
 //!
-//!           For example, if `P` is:
-//!           [
-//!               [Some(true), _],
-//!               [None, 0],
-//!           ]
-//!           and `p` is [Some(false), 0], then we don't care about row 2 since we know `p` only
-//!           matches values that row 2 doesn't. For row 1 however, we need to dig into the
-//!           arguments of `Some` to know whether some new value is covered. So we compute
-//!           `U([[true, _]], [false, 0])`.
+//! - If `p_1 == _`, then we look at the list of constructors that appear in the first component of
+//!   the rows of `P`:
+//!     - If there are some constructors that aren't present, then we might think that the
+//!       wildcard `_` is useful, since it covers those constructors that weren't covered
+//!       before.
+//!       That's almost correct, but only works if there were no wildcards in those first
+//!       components. So we need to check that `p` is useful with respect to the rows that
+//!       start with a wildcard, if there are any. This is where `D` comes in:
+//!       `U(P, p) := U(D(P), D(p))`
 //!
-//!         - If `p_1 == _`, then we look at the list of constructors that appear in the first
-//!               component of the rows of `P`:
-//!             + If there are some constructors that aren't present, then we might think that the
-//!               wildcard `_` is useful, since it covers those constructors that weren't covered
-//!               before.
-//!               That's almost correct, but only works if there were no wildcards in those first
-//!               components. So we need to check that `p` is useful with respect to the rows that
-//!               start with a wildcard, if there are any. This is where `D` comes in:
-//!               `U(P, p) := U(D(P), D(p))`
+//!       For example, if `P` is:
+//!       ```text
+//!       [
+//!           [_, true, _],
+//!           [None, false, 1],
+//!       ]
+//!       ```
+//!       and `p` is `[_, false, _]`, the `Some` constructor doesn't appear in `P`. So if we
+//!       only had row 2, we'd know that `p` is useful. However row 1 starts with a
+//!       wildcard, so we need to check whether `U([[true, _]], [false, 1])`.
 //!
-//!               For example, if `P` is:
-//!               [
-//!                   [_, true, _],
-//!                   [None, false, 1],
-//!               ]
-//!               and `p` is [_, false, _], the `Some` constructor doesn't appear in `P`. So if we
-//!               only had row 2, we'd know that `p` is useful. However row 1 starts with a
-//!               wildcard, so we need to check whether `U([[true, _]], [false, 1])`.
+//!     - Otherwise, all possible constructors (for the relevant type) are present. In this
+//!       case we must check whether the wildcard pattern covers any unmatched value. For
+//!       that, we can think of the `_` pattern as a big OR-pattern that covers all
+//!       possible constructors. For `Option`, that would mean `_ = None | Some(_)` for
+//!       example. The wildcard pattern is useful in this case if it is useful when
+//!       specialized to one of the possible constructors. So we compute:
+//!       `U(P, p) := ∃(k ϵ constructors) U(S(k, P), S(k, p))`
 //!
-//!             + Otherwise, all possible constructors (for the relevant type) are present. In this
-//!               case we must check whether the wildcard pattern covers any unmatched value. For
-//!               that, we can think of the `_` pattern as a big OR-pattern that covers all
-//!               possible constructors. For `Option`, that would mean `_ = None | Some(_)` for
-//!               example. The wildcard pattern is useful in this case if it is useful when
-//!               specialized to one of the possible constructors. So we compute:
-//!               `U(P, p) := ∃(k ϵ constructors) U(S(k, P), S(k, p))`
+//!       For example, if `P` is:
+//!       ```text
+//!       [
+//!           [Some(true), _],
+//!           [None, false],
+//!       ]
+//!       ```
+//!       and `p` is `[_, false]`, both `None` and `Some` constructors appear in the first
+//!       components of `P`. We will therefore try popping both constructors in turn: we
+//!       compute `U([[true, _]], [_, false])` for the `Some` constructor, and `U([[false]],
+//!       [false])` for the `None` constructor. The first case returns true, so we know that
+//!       `p` is useful for `P`. Indeed, it matches `[Some(false), _]` that wasn't matched
+//!       before.
 //!
-//!               For example, if `P` is:
-//!               [
-//!                   [Some(true), _],
-//!                   [None, false],
-//!               ]
-//!               and `p` is [_, false], both `None` and `Some` constructors appear in the first
-//!               components of `P`. We will therefore try popping both constructors in turn: we
-//!               compute U([[true, _]], [_, false]) for the `Some` constructor, and U([[false]],
-//!               [false]) for the `None` constructor. The first case returns true, so we know that
-//!               `p` is useful for `P`. Indeed, it matches `[Some(false), _]` that wasn't matched
-//!               before.
+//! - If `p_1 == r_1 | r_2`, then the usefulness depends on each `r_i` separately:
 //!
-//!         - If `p_1 == r_1 | r_2`, then the usefulness depends on each `r_i` separately:
-//!           `U(P, p) := U(P, (r_1, p_2, .., p_n))
-//!                    || U(P, (r_2, p_2, .., p_n))`
+//!   ```text
+//!   U(P, p) := U(P, (r_1, p_2, .., p_n))
+//!            || U(P, (r_2, p_2, .., p_n))
+//!   ```
 use std::sync::Arc;
 
 use smallvec::{smallvec, SmallVec};
diff --git a/crates/ra_ide/src/completion/completion_context.rs b/crates/ra_ide/src/completion/completion_context.rs
index 9f4c582d0..560fb19e6 100644
--- a/crates/ra_ide/src/completion/completion_context.rs
+++ b/crates/ra_ide/src/completion/completion_context.rs
@@ -381,6 +381,7 @@ impl<'a> CompletionContext<'a> {
             self.is_path_type = path.syntax().parent().and_then(ast::PathType::cast).is_some();
             self.has_type_args = segment.type_arg_list().is_some();
 
+            #[allow(deprecated)]
             if let Some(path) = hir::Path::from_ast(path.clone()) {
                 if let Some(path_prefix) = path.qualifier() {
                     self.path_prefix = Some(path_prefix);
diff --git a/crates/ra_parser/src/grammar/expressions.rs b/crates/ra_parser/src/grammar/expressions.rs
index d6e8df32a..6e72eea66 100644
--- a/crates/ra_parser/src/grammar/expressions.rs
+++ b/crates/ra_parser/src/grammar/expressions.rs
@@ -50,10 +50,8 @@ fn expr_no_struct(p: &mut Parser) {
 }
 
 fn is_expr_stmt_attr_allowed(kind: SyntaxKind) -> bool {
-    match kind {
-        BIN_EXPR | RANGE_EXPR | IF_EXPR => false,
-        _ => true,
-    }
+    let forbid = matches!(kind, BIN_EXPR | RANGE_EXPR);
+    !forbid
 }
 
 pub(super) fn stmt(p: &mut Parser, with_semi: StmtWithSemi) {
diff --git a/crates/ra_syntax/src/lib.rs b/crates/ra_syntax/src/lib.rs
index 61e686da5..a33a35cc1 100644
--- a/crates/ra_syntax/src/lib.rs
+++ b/crates/ra_syntax/src/lib.rs
@@ -51,7 +51,8 @@ pub use crate::{
     ptr::{AstPtr, SyntaxNodePtr},
     syntax_error::SyntaxError,
     syntax_node::{
-        Direction, NodeOrToken, SyntaxElement, SyntaxNode, SyntaxToken, SyntaxTreeBuilder,
+        Direction, NodeOrToken, SyntaxElement, SyntaxElementChildren, SyntaxNode,
+        SyntaxNodeChildren, SyntaxToken, SyntaxTreeBuilder,
     },
 };
 pub use ra_parser::{SyntaxKind, T};
diff --git a/crates/ra_syntax/test_data/parser/inline/err/0009_attr_on_expr_not_allowed.rast b/crates/ra_syntax/test_data/parser/inline/err/0009_attr_on_expr_not_allowed.rast
index 0656fdf73..4e3fa704e 100644
--- a/crates/ra_syntax/test_data/parser/inline/err/0009_attr_on_expr_not_allowed.rast
+++ b/crates/ra_syntax/test_data/parser/inline/err/0009_attr_on_expr_not_allowed.rast
@@ -56,4 +56,3 @@ [email protected]
       [email protected] "}"
   [email protected] "\n"
 error 24..24: attributes are not allowed on BIN_EXPR
-error 44..44: attributes are not allowed on IF_EXPR
diff --git a/crates/test_utils/src/lib.rs b/crates/test_utils/src/lib.rs
index 2141bfc20..981565cd7 100644
--- a/crates/test_utils/src/lib.rs
+++ b/crates/test_utils/src/lib.rs
@@ -10,17 +10,17 @@
 pub mod mark;
 
 use std::{
-    fs,
+    env, fs,
     path::{Path, PathBuf},
 };
 
-pub use ra_cfg::CfgOptions;
+use serde_json::Value;
 use stdx::split1;
+use text_size::{TextRange, TextSize};
 
+pub use ra_cfg::CfgOptions;
 pub use relative_path::{RelativePath, RelativePathBuf};
 pub use rustc_hash::FxHashMap;
-use serde_json::Value;
-use text_size::{TextRange, TextSize};
 
 pub use difference::Changeset as __Changeset;
 
@@ -625,8 +625,6 @@ pub fn skip_slow_tests() -> bool {
     should_skip
 }
 
-const REWRITE: bool = false;
-
 /// Asserts that `expected` and `actual` strings are equal. If they differ only
 /// in trailing or leading whitespace the test won't fail and
 /// the contents of `actual` will be written to the file located at `path`.
@@ -642,7 +640,7 @@ fn assert_equal_text(expected: &str, actual: &str, path: &Path) {
         fs::write(path, actual).unwrap();
         return;
     }
-    if REWRITE {
+    if env::var("UPDATE_EXPECTATIONS").is_ok() {
         println!("rewriting {}", pretty_path.display());
         fs::write(path, actual).unwrap();
         return;
diff --git a/docs/dev/README.md b/docs/dev/README.md
index 1ce8666e3..4cb5dfaa0 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -236,6 +236,13 @@ struct Foo {
 }
 ```
 
+## Variable Naming
+
+We generally 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 lowercased named of the type: `global_state: GlobalState`.
+Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently (`db`, `ctx`, `acc`).
+The default name for "result of the function" local variable is `res`.
+
 ## Preconditions
 
 Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee):
@@ -335,6 +342,12 @@ 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:
+
+```bash
+env UPDATE_EXPECTATIONS=1 cargo qt
+```
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to