9 files changed, 1838 insertions, 202 deletions

diff --git a/xtask/src/ast_src.rs b/xtask/src/ast_src.rs
index bdd42cb76..f60f0fb16 100644
--- a/xtask/src/ast_src.rs
+++ b/xtask/src/ast_src.rs
@@ -162,6 +162,7 @@ pub(crate) const KINDS_SRC: KindsSrc = KindsSrc {
         "RECORD_LIT",
         "RECORD_FIELD_LIST",
         "RECORD_FIELD",
+        "EFFECT_EXPR",
         "BOX_EXPR",
         // postfix
         "CALL_EXPR",
@@ -176,7 +177,6 @@ pub(crate) const KINDS_SRC: KindsSrc = KindsSrc {
         "PREFIX_EXPR",
         "RANGE_EXPR", // just weird
         "BIN_EXPR",
-        "BLOCK",
         "EXTERN_BLOCK",
         "EXTERN_ITEM_LIST",
         "ENUM_VARIANT",
@@ -230,6 +230,7 @@ pub(crate) struct AstSrc<'a> {
 }
 
 pub(crate) struct AstNodeSrc<'a> {
+    pub(crate) doc: &'a [&'a str],
     pub(crate) name: &'a str,
     pub(crate) traits: &'a [&'a str],
     pub(crate) fields: &'a [Field<'a>],
@@ -247,6 +248,7 @@ pub(crate) enum FieldSrc<'a> {
 }
 
 pub(crate) struct AstEnumSrc<'a> {
+    pub(crate) doc: &'a [&'a str],
     pub(crate) name: &'a str,
     pub(crate) traits: &'a [&'a str],
     pub(crate) variants: &'a [&'a str],
@@ -254,12 +256,14 @@ pub(crate) struct AstEnumSrc<'a> {
 
 macro_rules! ast_nodes {
     ($(
+        $(#[doc = $doc:expr])+
         struct $name:ident$(: $($trait:ident),*)? {
             $($field_name:ident $(![$token:tt])? $(: $ty:tt)?),*$(,)?
         }
     )*) => {
         [$(
             AstNodeSrc {
+                doc: &[$($doc),*],
                 name: stringify!($name),
                 traits: &[$($(stringify!($trait)),*)?],
                 fields: &[
@@ -288,12 +292,14 @@ macro_rules! field {
 
 macro_rules! ast_enums {
     ($(
+        $(#[doc = $doc:expr])+
         enum $name:ident $(: $($trait:ident),*)? {
             $($variant:ident),*$(,)?
         }
     )*) => {
         [$(
             AstEnumSrc {
+                doc: &[$($doc),*],
                 name: stringify!($name),
                 traits: &[$($(stringify!($trait)),*)?],
                 variants: &[$(stringify!($variant)),*],
@@ -305,10 +311,35 @@ macro_rules! ast_enums {
 pub(crate) const AST_SRC: AstSrc = AstSrc {
     tokens: &["Whitespace", "Comment", "String", "RawString"],
     nodes: &ast_nodes! {
-        struct SourceFile: ModuleItemOwner, AttrsOwner {
+        /// The entire Rust source file. Includes all top-level inner attributes and module items.
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/crates-and-source-files.html)
+        struct SourceFile: ModuleItemOwner, AttrsOwner, DocCommentsOwner {
             modules: [Module],
         }
 
+        /// Function definition either with body or not.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub extern "C" fn foo<T>(#[attr] Patern {p}: Pattern) -> u32
+        ///     where
+        ///         T: Debug
+        ///     {
+        ///         42
+        ///     }
+        /// ❱
+        ///
+        /// extern "C" {
+        ///     ❰ fn fn_decl(also_variadic_ffi: u32, ...) -> u32; ❱
+        /// }
+        /// ```
+        ///
+        /// - [Reference](https://doc.rust-lang.org/reference/items/functions.html)
+        /// - [Nomicon](https://doc.rust-lang.org/nomicon/ffi.html#variadic-functions)
         struct FnDef: VisibilityOwner, NameOwner, TypeParamsOwner, DocCommentsOwner, AttrsOwner {
             Abi,
             T![const],
@@ -322,42 +353,201 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             T![;]
         }
 
+        /// Return type annotation.
+        ///
+        /// ```
+        /// fn foo(a: u32) ❰ -> Option<u32> ❱ { Some(a) }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/functions.html)
         struct RetType { T![->], TypeRef }
 
+        /// Struct definition.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     struct Foo<T> where T: Debug {
+        ///         /// Docs
+        ///         #[attr]
+        ///         pub a: u32,
+        ///         b: T,
+        ///     }
+        /// ❱
+        ///
+        /// ❰ struct Foo; ❱
+        /// ❰ struct Foo<T>(#[attr] T) where T: Debug; ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
         struct StructDef: VisibilityOwner, NameOwner, TypeParamsOwner, AttrsOwner, DocCommentsOwner {
             T![struct],
             FieldDefList,
             T![;]
         }
 
+        /// Union definition.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub union Foo<T> where T: Debug {
+        ///         /// Docs
+        ///         #[attr]
+        ///         a: T,
+        ///         b: u32,
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/unions.html)
         struct UnionDef: VisibilityOwner, NameOwner, TypeParamsOwner, AttrsOwner, DocCommentsOwner {
             T![union],
             RecordFieldDefList,
         }
 
+        /// Record field definition list including enclosing curly braces.
+        ///
+        /// ```
+        /// struct Foo // same for union
+        /// ❰
+        ///     {
+        ///         a: u32,
+        ///         b: bool,
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
         struct RecordFieldDefList { T!['{'], fields: [RecordFieldDef], T!['}'] }
+
+        /// Record field definition including its attributes and doc comments.
+        ///
+        /// ` ``
+        /// same for union
+        /// struct Foo {
+        ///      ❰
+        ///          /// Docs
+        ///          #[attr]
+        ///          pub a: u32
+        ///      ❱
+        ///
+        ///      ❰ b: bool ❱
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
         struct RecordFieldDef: VisibilityOwner, NameOwner, AttrsOwner, DocCommentsOwner, TypeAscriptionOwner { }
 
+        /// Tuple field definition list including enclosing parens.
+        ///
+        /// ```
+        /// struct Foo ❰ (u32, String, Vec<u32>) ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
         struct TupleFieldDefList { T!['('], fields: [TupleFieldDef], T![')'] }
+
+        /// Tuple field definition including its attributes.
+        ///
+        /// ```
+        /// struct Foo(❰ #[attr] u32 ❱);
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
         struct TupleFieldDef: VisibilityOwner, AttrsOwner {
             TypeRef,
         }
 
+        /// Enum definition.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub enum Foo<T> where T: Debug {
+        ///         /// Docs
+        ///         #[attr]
+        ///         Bar,
+        ///         Baz(#[attr] u32),
+        ///         Bruh {
+        ///             a: u32,
+        ///             /// Docs
+        ///             #[attr]
+        ///             b: T,
+        ///         }
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/enumerations.html)
         struct EnumDef: VisibilityOwner, NameOwner, TypeParamsOwner, AttrsOwner, DocCommentsOwner {
             T![enum],
             variant_list: EnumVariantList,
         }
+
+        /// Enum variant definition list including enclosing curly braces.
+        ///
+        /// ```
+        /// enum Foo
+        /// ❰
+        ///     {
+        ///         Bar,
+        ///         Baz(u32),
+        ///         Bruh {
+        ///             a: u32
+        ///         }
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/enumerations.html)
         struct EnumVariantList {
             T!['{'],
             variants: [EnumVariant],
             T!['}']
         }
+
+        /// Enum variant definition including its attributes and discriminant value definition.
+        ///
+        /// ```
+        /// enum Foo {
+        ///     ❰
+        ///         /// Docs
+        ///         #[attr]
+        ///         Bar
+        ///     ❱
+        ///
+        ///     // same for tuple and record variants
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/enumerations.html)
         struct EnumVariant: VisibilityOwner, NameOwner, DocCommentsOwner, AttrsOwner {
             FieldDefList,
             T![=],
             Expr
         }
 
+        /// Trait definition.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub unsafe trait Foo<T>: Debug where T: Debug {
+        ///         // ...
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/traits.html)
         struct TraitDef: VisibilityOwner, NameOwner, AttrsOwner, DocCommentsOwner, TypeParamsOwner, TypeBoundsOwner {
             T![unsafe],
             T![auto],
@@ -365,18 +555,73 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             ItemList,
         }
 
+        /// Module definition either with body or not.
+        /// Includes all of its inner and outer attributes, module items, doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub mod foo;
+        /// ❱
+        ///
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub mod bar {
+        ///        //! Inner docs
+        ///        #![inner_attr]
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/modules.html)
         struct Module: VisibilityOwner, NameOwner, AttrsOwner, DocCommentsOwner {
             T![mod],
             ItemList,
             T![;]
         }
 
+        /// Item defintion list.
+        /// This is used for both top-level items and impl block items.
+        ///
+        /// ```
+        /// ❰
+        ///     fn foo {}
+        ///     struct Bar;
+        ///     enum Baz;
+        ///     trait Bruh;
+        ///     const BRUUH: u32 = 42;
+        /// ❱
+        ///
+        /// impl Foo
+        /// ❰
+        ///     {
+        ///         fn bar() {}
+        ///         const BAZ: u32 = 42;
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items.html)
         struct ItemList: ModuleItemOwner {
             T!['{'],
-            impl_items: [ImplItem],
+            assoc_items: [AssocItem],
             T!['}']
         }
 
+        /// Constant variable definition.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub const FOO: u32 = 42;
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/constant-items.html)
         struct ConstDef: VisibilityOwner, NameOwner, TypeParamsOwner, AttrsOwner, DocCommentsOwner, TypeAscriptionOwner {
             T![default],
             T![const],
@@ -385,6 +630,19 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             T![;]
         }
 
+
+        /// Static variable definition.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub static mut FOO: u32 = 42;
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/static-items.html)
         struct StaticDef: VisibilityOwner, NameOwner, TypeParamsOwner, AttrsOwner, DocCommentsOwner, TypeAscriptionOwner {
             T![static],
             T![mut],
@@ -393,6 +651,24 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             T![;]
         }
 
+        /// Type alias definition.
+        /// Includes associated type clauses with type bounds.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     pub type Foo<T> where T: Debug = T;
+        /// ❱
+        ///
+        /// trait Bar {
+        ///     ❰ type Baz: Debug; ❱
+        ///     ❰ type Bruh = String; ❱
+        ///     ❰ type Bruuh: Debug = u32; ❱
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/type-aliases.html)
         struct TypeAliasDef: VisibilityOwner, NameOwner, TypeParamsOwner, AttrsOwner, DocCommentsOwner, TypeBoundsOwner {
             T![default],
             T![type],
@@ -401,7 +677,21 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             T![;]
         }
 
-        struct ImplDef: TypeParamsOwner, AttrsOwner {
+        /// Inherent and trait impl definition.
+        /// Includes all of its inner and outer attributes.
+        ///
+        /// ```
+        /// ❰
+        ///     #[attr]
+        ///     unsafe impl<T> const !Foo for Bar where T: Debug {
+        ///         #![inner_attr]
+        ///         // ...
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/implementations.html)
+        struct ImplDef: TypeParamsOwner, AttrsOwner, DocCommentsOwner {
             T![default],
             T![const],
             T![unsafe],
@@ -411,73 +701,613 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             ItemList,
         }
 
+
+        /// Parenthesized type reference.
+        /// Note: parens are only used for grouping, this is not a tuple type.
+        ///
+        /// ```
+        /// // This is effectively just `u32`.
+        /// // Single-item tuple must be defined with a trailing comma: `(u32,)`
+        /// type Foo = ❰ (u32) ❱;
+        ///
+        /// let bar: &'static ❰ (dyn Debug) ❱ = "bruh";
+        /// ```
         struct ParenType { T!['('], TypeRef, T![')'] }
+
+        /// Unnamed tuple type.
+        ///
+        /// ```
+        /// let foo: ❰ (u32, bool) ❱ = (42, true);
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/tuple.html)
         struct TupleType { T!['('], fields: [TypeRef], T![')'] }
+
+        /// The never type (i.e. the exclamation point).
+        ///
+        /// ```
+        /// type T = ❰ ! ❱;
+        ///
+        /// fn no_return() -> ❰ ! ❱ {
+        ///     loop {}
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/never.html)
         struct NeverType { T![!] }
+
+        /// Path to a type.
+        /// Includes single identifier type names and elaborate paths with
+        /// generic parameters.
+        ///
+        /// ```
+        /// type Foo = ❰ String ❱;
+        /// type Bar = ❰ std::vec::Vec<T> ❱;
+        /// type Baz = ❰ ::bruh::<Bruuh as Iterator>::Item ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/paths.html)
         struct PathType { Path }
+
+        /// Raw pointer type.
+        ///
+        /// ```
+        /// type Foo = ❰ *const u32 ❱;
+        /// type Bar = ❰ *mut u32 ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/pointer.html#raw-pointers-const-and-mut)
         struct PointerType { T![*], T![const], T![mut], TypeRef }
+
+        /// Array type.
+        ///
+        /// ```
+        /// type Foo = ❰ [u32; 24 - 3] ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/array.html)
         struct ArrayType { T!['['], TypeRef, T![;], Expr, T![']'] }
+
+        /// Slice type.
+        ///
+        /// ```
+        /// type Foo = ❰ [u8] ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/slice.html)
         struct SliceType { T!['['], TypeRef, T![']'] }
+
+        /// Reference type.
+        ///
+        /// ```
+        /// type Foo = ❰ &'static str ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/pointer.html)
         struct ReferenceType { T![&], T![lifetime], T![mut], TypeRef }
+
+        /// Placeholder type (i.e. the underscore).
+        ///
+        /// ```
+        /// let foo: ❰ _ ❱ = 42_u32;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/inferred.html)
         struct PlaceholderType { T![_] }
+
+        /// Function pointer type (not to be confused with `Fn*` family of traits).
+        ///
+        /// ```
+        /// type Foo = ❰ async fn(#[attr] u32, named: bool) -> u32 ❱;
+        ///
+        /// type Bar = ❰ extern "C" fn(variadic: u32, #[attr] ...) ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/function-pointer.html)
         struct FnPointerType { Abi, T![unsafe], T![fn], ParamList, RetType }
+
+        /// Higher order type.
+        ///
+        /// ```
+        /// type Foo = ❰ for<'a> fn(&'a str) ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/nomicon/hrtb.html)
         struct ForType { T![for], TypeParamList, TypeRef }
+
+        /// Opaque `impl Trait` type.
+        ///
+        /// ```
+        /// fn foo(bar: ❰ impl Debug + Eq ❱) {}
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/impl-trait.html)
         struct ImplTraitType: TypeBoundsOwner { T![impl] }
+
+        /// Trait object type.
+        ///
+        /// ```
+        /// type Foo = ❰ dyn Debug ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/types/trait-object.html)
         struct DynTraitType: TypeBoundsOwner { T![dyn] }
 
+        /// Tuple literal.
+        ///
+        /// ```
+        /// ❰ (42, true) ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/tuple-expr.html)
         struct TupleExpr: AttrsOwner { T!['('], exprs: [Expr], T![')'] }
+
+        /// Array literal.
+        ///
+        /// ```
+        /// ❰ [#![inner_attr] true, false, true] ❱;
+        ///
+        /// ❰ ["baz"; 24] ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/array-expr.html)
         struct ArrayExpr: AttrsOwner { T!['['], exprs: [Expr], T![;], T![']'] }
+
+        /// Parenthesized expression.
+        /// Note: parens are only used for grouping, this is not a tuple literal.
+        ///
+        /// ```
+        /// ❰ (#![inner_attr] 2 + 2) ❱ * 2;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/grouped-expr.html)
         struct ParenExpr: AttrsOwner { T!['('], Expr, T![')'] }
-        struct PathExpr  { Path }
+
+        /// Path to a symbol in expression context.
+        /// Includes single identifier variable names and elaborate paths with
+        /// generic parameters.
+        ///
+        /// ```
+        /// ❰ Some::<i32> ❱;
+        /// ❰ foo ❱ + 42;
+        /// ❰ Vec::<i32>::push ❱;
+        /// ❰ <[i32]>::reverse ❱;
+        /// ❰ <String as std::borrow::Borrow<str>>::borrow ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/path-expr.html)
+        struct PathExpr { Path }
+
+        /// Anonymous callable object literal a.k.a. closure, lambda or functor.
+        ///
+        /// ```
+        /// ❰ || 42 ❱;
+        /// ❰ |a: u32| val + 1 ❱;
+        /// ❰ async |#[attr] Pattern(_): Pattern| { bar } ❱;
+        /// ❰ move || baz ❱;
+        /// ❰ || -> u32 { closure_with_ret_type_annotation_requires_block_expr } ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/closure-expr.html)
         struct LambdaExpr: AttrsOwner {
-            T![static],
+            T![static], // Note(@matklad): I belive this is (used to be?) syntax for generators
             T![async],
             T![move],
             ParamList,
             RetType,
             body: Expr,
         }
+
+        /// If expression. Includes both regular `if` and `if let` forms.
+        /// Beware that `else if` is a special case syntax sugar, because in general
+        /// there has to be block expression after `else`.
+        ///
+        /// ```
+        /// ❰ if bool_cond { 42 } ❱
+        /// ❰ if bool_cond { 42 } else { 24 } ❱
+        /// ❰ if bool_cond { 42 } else if bool_cond2 { 42 } ❱
+        ///
+        /// ❰
+        ///     if let Pattern(foo) = bar {
+        ///         foo
+        ///     } else {
+        ///         panic!();
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/if-expr.html)
         struct IfExpr: AttrsOwner { T![if], Condition }
+
+        /// Unconditional loop expression.
+        ///
+        /// ```
+        /// ❰
+        ///     loop {
+        ///         // yeah, it's that simple...
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html)
         struct LoopExpr: AttrsOwner, LoopBodyOwner { T![loop] }
+
+        /// Block expression with an optional prefix (label, try ketword,
+        /// unsafe keyword, async keyword...).
+        ///
+        /// ```
+        /// ❰
+        ///     'label: try {
+        ///         None?
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// - [try block](https://doc.rust-lang.org/unstable-book/language-features/try-blocks.html)
+        /// - [unsafe block](https://doc.rust-lang.org/reference/expressions/block-expr.html#unsafe-blocks)
+        /// - [async block](https://doc.rust-lang.org/reference/expressions/block-expr.html#async-blocks)
+        struct EffectExpr: AttrsOwner { Label, T![try], T![unsafe], T![async], BlockExpr }
+
+
+        /// For loop expression.
+        /// Note: record struct literals are not valid as iterable expression
+        /// due to ambiguity.
+        ///
+        /// ```
+        /// ❰
+        /// for i in (0..4) {
+        ///     dbg!(i);
+        /// }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html#iterator-loops)
         struct ForExpr: AttrsOwner, LoopBodyOwner {
             T![for],
             Pat,
             T![in],
             iterable: Expr,
         }
+
+        /// While loop expression. Includes both regular `while` and `while let` forms.
+        ///
+        /// ```
+        /// ❰
+        ///     while bool_cond {
+        ///         42;
+        ///     }
+        /// ❱
+        /// ❰
+        ///     while let Pattern(foo) = bar {
+        ///         bar += 1;
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-loops)
         struct WhileExpr: AttrsOwner, LoopBodyOwner { T![while], Condition }
+
+        /// Continue expression.
+        ///
+        /// ```
+        /// while bool_cond {
+        ///     ❰ continue ❱;
+        /// }
+        ///
+        /// 'outer: loop {
+        ///     loop {
+        ///         ❰ continue 'outer ❱;
+        ///     }
+        /// }
+        ///
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html#continue-expressions)
         struct ContinueExpr: AttrsOwner { T![continue], T![lifetime] }
+
+        /// Break expression.
+        ///
+        /// ```
+        /// while bool_cond {
+        ///     ❰ break ❱;
+        /// }
+        /// 'outer: loop {
+        ///     for foo in bar {
+        ///         ❰ break 'outer ❱;
+        ///     }
+        /// }
+        /// 'outer: loop {
+        ///     loop {
+        ///         ❰ break 'outer 42 ❱;
+        ///     }
+        /// }
+        /// ```
+        ///
+        /// [Refernce](https://doc.rust-lang.org/reference/expressions/loop-expr.html#break-expressions)
         struct BreakExpr: AttrsOwner { T![break], T![lifetime], Expr }
+
+        /// Label.
+        ///
+        /// ```
+        /// ❰ 'outer: ❱ loop {}
+        ///
+        /// let foo = ❰ 'bar: ❱ loop {}
+        ///
+        /// ❰ 'baz: ❱ {
+        ///     break 'baz;
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html?highlight=label#loop-labels)
+        /// [Labels for blocks RFC](https://github.com/rust-lang/rfcs/blob/master/text/2046-label-break-value.md)
         struct Label { T![lifetime] }
-        struct BlockExpr: AttrsOwner { Label, T![unsafe], T![async], Block }
+
+        /// Block expression. Includes unsafe blocks and block labels.
+        ///
+        /// ```
+        ///     let foo = ❰
+        ///         {
+        ///             #![inner_attr]
+        ///             ❰ { } ❱
+        ///
+        ///             ❰ 'label: { break 'label } ❱
+        ///         }
+        ///     ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/block-expr.html)
+        /// [Labels for blocks RFC](https://github.com/rust-lang/rfcs/blob/master/text/2046-label-break-value.md)
+        struct BlockExpr: AttrsOwner, ModuleItemOwner {
+            Label, T!['{'], statements: [Stmt], Expr, T!['}'],
+        }
+
+        /// Return expression.
+        ///
+        /// ```
+        /// || ❰ return 42 ❱;
+        ///
+        /// fn bar() {
+        ///     ❰ return ❱;
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/return-expr.html)
         struct ReturnExpr: AttrsOwner { Expr }
+
+        /// Call expression (not to be confused with method call expression, it is
+        /// a separate ast node).
+        ///
+        /// ```
+        /// ❰ foo() ❱;
+        /// ❰ &str::len("bar") ❱;
+        /// ❰ <&str as PartialEq<&str>>::eq(&"", &"") ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/call-expr.html)
         struct CallExpr: ArgListOwner { Expr }
+
+        /// Method call expression.
+        ///
+        /// ```
+        /// ❰ receiver_expr.method() ❱;
+        /// ❰ receiver_expr.method::<T>(42, true) ❱;
+        ///
+        /// ❰ ❰ ❰ foo.bar() ❱ .baz() ❱ .bruh() ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/method-call-expr.html)
         struct MethodCallExpr: AttrsOwner, ArgListOwner {
             Expr, T![.], NameRef, TypeArgList,
         }
+
+        /// Index expression a.k.a. subscript operator call.
+        ///
+        /// ```
+        /// ❰ foo[42] ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/array-expr.html)
         struct IndexExpr: AttrsOwner { T!['['], T![']'] }
+
+        /// Field access expression.
+        ///
+        /// ```
+        /// ❰ expr.bar ❱;
+        ///
+        /// ❰ ❰ ❰ foo.bar ❱ .baz ❱ .bruh ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/field-expr.html)
         struct FieldExpr: AttrsOwner { Expr, T![.], NameRef }
+
+        /// Await operator call expression.
+        ///
+        /// ```
+        /// ❰ expr.await ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/await-expr.html)
         struct AwaitExpr: AttrsOwner { Expr, T![.], T![await] }
-        struct TryExpr: AttrsOwner { T![try], Expr }
+
+        /// The question mark operator call.
+        ///
+        /// ```
+        /// ❰ expr? ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator)
+        struct TryExpr: AttrsOwner { Expr, T![?] }
+
+        /// Type cast expression.
+        ///
+        /// ```
+        /// ❰ expr as T ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions)
         struct CastExpr: AttrsOwner { Expr, T![as], TypeRef }
-        struct RefExpr: AttrsOwner { T![&], T![raw], T![mut], Expr }
+
+
+        /// Borrow operator call.
+        ///
+        /// ```
+        /// ❰ &foo ❱;
+        /// ❰ &mut bar ❱;
+        /// ❰ &raw const bar ❱;
+        /// ❰ &raw mut bar ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#borrow-operators)
+        struct RefExpr: AttrsOwner { T![&], T![raw], T![mut], T![const], Expr }
+
+        /// Prefix operator call. This is either `!` or `*` or `-`.
+        ///
+        /// ```
+        /// ❰ !foo ❱;
+        /// ❰ *bar ❱;
+        /// ❰ -42 ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html)
         struct PrefixExpr: AttrsOwner { /*PrefixOp,*/ Expr }
+
+        /// Box operator call.
+        ///
+        /// ```
+        /// ❰ box 42 ❱;
+        /// ```
+        ///
+        /// [RFC](https://github.com/rust-lang/rfcs/blob/0806be4f282144cfcd55b1d20284b43f87cbe1c6/text/0809-box-and-in-for-stdlib.md)
         struct BoxExpr: AttrsOwner { T![box], Expr }
+
+        /// Range operator call.
+        ///
+        /// ```
+        /// ❰ 0..42 ❱;
+        /// ❰ ..42 ❱;
+        /// ❰ 0.. ❱;
+        /// ❰ .. ❱;
+        /// ❰ 0..=42 ❱;
+        /// ❰ ..=42 ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/range-expr.html)
         struct RangeExpr: AttrsOwner { /*RangeOp*/ }
+
+
+        /// Binary operator call.
+        /// Includes all arithmetic, logic, bitwise and assignment operators.
+        ///
+        /// ```
+        /// ❰ 2 + ❰ 2 * 2 ❱ ❱;
+        /// ❰ ❰ true && false ❱ || true ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#arithmetic-and-logical-binary-operators)
         struct BinExpr: AttrsOwner { /*BinOp*/ }
+
+
+        /// [Raw] string, [raw] byte string, char, byte, integer, float or bool literal.
+        ///
+        /// ```
+        /// ❰ "str" ❱;
+        /// ❰ br##"raw byte str"## ❱;
+        /// ❰ 'c' ❱;
+        /// ❰ b'c' ❱;
+        /// ❰ 42 ❱;
+        /// ❰ 1e9 ❱;
+        /// ❰ true ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/literal-expr.html)
         struct Literal { /*LiteralToken*/ }
 
+        /// Match expression.
+        ///
+        /// ```
+        /// ❰
+        ///     match expr {
+        ///         Pat1 => {}
+        ///         Pat2(_) => 42,
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/match-expr.html)
         struct MatchExpr: AttrsOwner { T![match], Expr, MatchArmList }
+
+        /// Match arm list part of match expression. Includes its inner attributes.
+        ///
+        /// ```
+        /// match expr
+        /// ❰
+        ///     {
+        ///         #![inner_attr]
+        ///         Pat1 => {}
+        ///         Pat2(_) => 42,
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/match-expr.html)
         struct MatchArmList: AttrsOwner { T!['{'], arms: [MatchArm], T!['}'] }
+
+
+        /// Match arm.
+        /// Note: record struct literals are not valid as target match expression
+        /// due to ambiguity.
+        /// ```
+        /// match expr {
+        ///     ❰ #[attr] Pattern(it) if bool_cond => it ❱,
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/match-expr.html)
         struct MatchArm: AttrsOwner {
             pat: Pat,
             guard: MatchGuard,
             T![=>],
             Expr,
         }
+
+        /// Match guard.
+        ///
+        /// ```
+        /// match expr {
+        ///     Pattern(it) ❰ if bool_cond ❱ => it,
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/match-expr.html#match-guards)
         struct MatchGuard { T![if], Expr }
 
+        /// Record literal expression. The same syntax is used for structs,
+        /// unions and record enum variants.
+        ///
+        /// ```
+        /// ❰
+        ///     foo::Bar {
+        ///         #![inner_attr]
+        ///         baz: 42,
+        ///         bruh: true,
+        ///         ..spread
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/struct-expr.html)
         struct RecordLit { Path, RecordFieldList}
+
+        /// Record field list including enclosing curly braces.
+        ///
+        /// foo::Bar ❰
+        ///     {
+        ///         baz: 42,
+        ///         ..spread
+        ///     }
+        /// ❱
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/struct-expr.html)
         struct RecordFieldList {
             T!['{'],
             fields: [RecordField],
@@ -485,22 +1315,162 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             spread: Expr,
             T!['}']
         }
+
+        /// Record field.
+        ///
+        /// ```
+        /// foo::Bar {
+        ///     ❰ #[attr] baz: 42 ❱
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/struct-expr.html)
         struct RecordField: AttrsOwner { NameRef, T![:], Expr }
 
+        /// Disjunction of patterns.
+        ///
+        /// ```
+        /// let ❰ Foo(it) | Bar(it) | Baz(it) ❱ = bruh;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html)
         struct OrPat { pats: [Pat] }
+
+        /// Parenthesized pattern.
+        /// Note: parens are only used for grouping, this is not a tuple pattern.
+        ///
+        /// ```
+        /// if let ❰ &(0..=42) ❱ = foo {}
+        /// ```
+        ///
+        /// https://doc.rust-lang.org/reference/patterns.html#grouped-patterns
         struct ParenPat { T!['('], Pat, T![')'] }
+
+        /// Reference pattern.
+        /// Note: this has nothing to do with `ref` keyword, the latter is used in bind patterns.
+        ///
+        /// ```
+        /// let ❰ &mut foo ❱ = bar;
+        ///
+        /// let ❰ & ❰ &mut ❰ &_ ❱ ❱ ❱ = baz;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#reference-patterns)
         struct RefPat { T![&], T![mut], Pat }
+
+        /// Box pattern.
+        ///
+        /// ```
+        /// let ❰ box foo ❱ = box 42;
+        /// ```
+        ///
+        /// [Unstable book](https://doc.rust-lang.org/unstable-book/language-features/box-patterns.html)
         struct BoxPat { T![box], Pat }
+
+        /// Bind pattern.
+        ///
+        /// ```
+        /// match foo {
+        ///     Some(❰ ref mut bar ❱) => {}
+        ///     ❰ baz @ None ❱ => {}
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#identifier-patterns)
         struct BindPat: AttrsOwner, NameOwner { T![ref], T![mut], T![@], Pat }
+
+        /// Placeholder pattern a.k.a. the wildcard pattern or the underscore.
+        ///
+        /// ```
+        /// let ❰ _ ❱ = foo;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#wildcard-pattern)
         struct PlaceholderPat { T![_] }
+
+        /// Rest-of-the record/tuple pattern.
+        /// Note: this is not the unbonded range pattern (even more: it doesn't exist).
+        ///
+        /// ```
+        /// let Foo { bar, ❰ .. ❱ } = baz;
+        /// let (❰ .. ❱, bruh) = (42, 24, 42);
+        /// let Bruuh(❰ .. ❱) = bruuuh;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#struct-patterns)
         struct DotDotPat { T![..] }
+
+        /// Path pattern.
+        /// Doesn't include the underscore pattern (it is a special case, namely `PlaceholderPat`).
+        ///
+        /// ```
+        /// let ❰ foo::bar::Baz ❱ { .. } = bruh;
+        /// if let ❰ CONST ❱ = 42 {}
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#path-patterns)
         struct PathPat { Path }
+
+        /// Slice pattern.
+        ///
+        /// ```
+        /// let ❰ [foo, bar, baz] ❱ = [1, 2, 3];
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#slice-patterns)
         struct SlicePat { T!['['], args: [Pat], T![']'] }
-        struct RangePat { /*RangeSeparator*/ }
+
+        /// Range pattern.
+        ///
+        /// ```
+        /// match foo {
+        ///     ❰ 0..42 ❱ => {}
+        ///     ❰ 0..=42 ❱ => {}
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#range-patterns)
+        struct RangePat { } // FIXME(@matklad): here should be T![..], T![..=] I think, if we don't already have an accessor in expresions_ext
+
+        /// Literal pattern.
+        /// Includes only bool, number, char, and string literals.
+        ///
+        /// ```
+        /// match foo {
+        ///     Number(❰ 42 ❱) => {}
+        ///     String(❰ "42" ❱) => {}
+        ///     Bool(❰ true ❱) => {}
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#literal-patterns)
         struct LiteralPat { Literal }
+
+        /// Macro invocation in pattern position.
+        ///
+        /// ```
+        /// let ❰ foo!(my custom syntax) ❱ = baz;
+        ///
+        /// ```
+        /// [Reference](https://doc.rust-lang.org/reference/macros.html#macro-invocation)
         struct MacroPat { MacroCall }
 
+        /// Record literal pattern.
+        ///
+        /// ```
+        /// let ❰ foo::Bar { baz, .. } ❱ = bruh;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#struct-patterns)
         struct RecordPat { RecordFieldPatList, Path }
+
+        /// Record literal's field patterns list including enclosing curly braces.
+        ///
+        /// ```
+        /// let foo::Bar ❰ { baz, bind @ bruh, .. } ❱ = bruuh;
+        /// ``
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#struct-patterns)
         struct RecordFieldPatList {
             T!['{'],
             pats: [RecordInnerPat],
@@ -509,20 +1479,148 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             T![..],
             T!['}']
         }
+
+        /// Record literal's field pattern.
+        /// Note: record literal can also match tuple structs.
+        ///
+        /// ```
+        /// let Foo { ❰ bar: _ ❱ } = baz;
+        /// let TupleStruct { ❰ 0: _ ❱ } = bruh;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#struct-patterns)
         struct RecordFieldPat: AttrsOwner { NameRef, T![:], Pat }
 
+        /// Tuple struct literal pattern.
+        ///
+        /// ```
+        /// let ❰ foo::Bar(baz, bruh) ❱ = bruuh;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#tuple-struct-patterns)
         struct TupleStructPat { Path, T!['('], args: [Pat], T![')'] }
+
+        /// Tuple pattern.
+        /// Note: this doesn't include tuple structs (see `TupleStructPat`)
+        ///
+        /// ```
+        /// let ❰ (foo, bar, .., baz) ❱ = bruh;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/patterns.html#tuple-patterns)
         struct TuplePat { T!['('], args: [Pat], T![')'] }
 
+        /// Visibility.
+        ///
+        /// ```
+        /// ❰ pub mod ❱ foo;
+        /// ❰ pub(crate) ❱ struct Bar;
+        /// ❰ pub(self) ❱ enum Baz {}
+        /// ❰ pub(super) ❱ fn bruh() {}
+        /// ❰ pub(in bruuh::bruuuh) ❱ type T = u64;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/visibility-and-privacy.html)
         struct Visibility { T![pub], T![super], T![self], T![crate] }
+
+        /// Single identifier.
+        /// Note(@matklad): `Name` is for things that install a new name into the scope,
+        /// `NameRef` is a usage of a name. Most of the time, this definition/reference
+        /// distinction can be determined purely syntactically, ie in
+        /// ```
+        /// fn foo() { foo() }
+        /// ```
+        /// the first foo is `Name`, the second one is `NameRef`.
+        /// The notable exception are patterns, where in
+        /// ``
+        /// let x = 92
+        /// ```
+        /// `x` can be semantically either a name or a name ref, depeding on
+        /// wether there's an `x` constant in scope.
+        /// We use `Name` for patterns, and disambiguate semantically (see `NameClass` in ide_db).
+        ///
+        /// ```
+        /// let ❰ foo ❱ = bar;
+        /// struct ❰ Baz ❱;
+        /// fn ❰ bruh ❱() {}
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/identifiers.html)
         struct Name { T![ident] }
-        struct NameRef { /*NameRefToken*/ }
 
-        struct MacroCall: NameOwner, AttrsOwner,DocCommentsOwner {
+        /// Reference to a name.
+        /// See the explanation on the difference between `Name` and `NameRef`
+        /// in `Name` ast node docs.
+        ///
+        /// ```
+        /// let foo = ❰ bar ❱(❰ Baz(❰ bruh ❱) ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/identifiers.html)
+        struct NameRef { }
+
+        /// Macro call.
+        /// Includes all of its attributes and doc comments.
+        ///
+        /// ```
+        /// ❰
+        ///     /// Docs
+        ///     #[attr]
+        ///     macro_rules! foo {   // macro rules is also a macro call
+        ///         ($bar: tt) => {}
+        ///     }
+        /// ❱
+        ///
+        /// // semicolon is a part of `MacroCall` when it is used in item positions
+        /// ❰ foo!(); ❱
+        ///
+        /// fn main() {
+        ///     ❰ foo!() ❱; // macro call in expression positions doesn't include the semi
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/macros.html)
+        struct MacroCall: NameOwner, AttrsOwner, DocCommentsOwner {
             Path, T![!], TokenTree, T![;]
         }
+
+        /// Attribute.
+        ///
+        /// ```
+        /// ❰ #![inner_attr] ❱
+        ///
+        /// ❰ #[attr] ❱
+        /// ❰ #[foo = "bar"] ❱
+        /// ❰ #[baz(bruh::bruuh = "42")] ❱
+        /// struct Foo;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/attributes.html)
         struct Attr { T![#], T![!], T!['['], Path, T![=], input: AttrInput, T![']'] }
+
+        /// Stores a list of lexer tokens and other `TokenTree`s.
+        /// It appears in attributes, macro_rules and macro call (foo!)
+        ///
+        /// ```
+        /// macro_call! ❰ { my syntax here } ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/macros.html)
         struct TokenTree {}
+
+        /// Generic lifetime, type and constants parameters list **declaration**.
+        ///
+        /// ```
+        /// fn foo❰ <'a, 'b, T, U, const BAR: u64> ❱() {}
+        ///
+        /// struct Baz❰ <T> ❱(T);
+        ///
+        /// impl❰ <T> ❱ Bruh<T> {}
+        ///
+        /// type Bruuh = for❰ <'a> ❱ fn(&'a str) -> &'a str;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/generics.html)
         struct TypeParamList {
             T![<],
             generic_params: [GenericParam],
@@ -531,21 +1629,141 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             const_params: [ConstParam],
             T![>]
         }
+
+        /// Single type parameter **declaration**.
+        ///
+        /// ```
+        /// fn foo<❰ K ❱, ❰ I ❱, ❰ E: Debug ❱, ❰ V = DefaultType ❱>() {}
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/generics.html)
         struct TypeParam: NameOwner, AttrsOwner, TypeBoundsOwner {
             T![=],
             default_type: TypeRef,
         }
+
+        /// Const generic parameter **declaration**.
+        /// ```
+        /// fn foo<T, U, ❰ const BAR: usize ❱, ❰ const BAZ: bool ❱>() {}
+        /// ```
+        ///
+        /// [RFC](https://github.com/rust-lang/rfcs/blob/master/text/2000-const-generics.md#declaring-a-const-parameter)
         struct ConstParam: NameOwner, AttrsOwner, TypeAscriptionOwner {
             T![=],
             default_val: Expr,
         }
+
+        /// Lifetime parameter **declaration**.
+        ///
+        /// ```
+        /// fn foo<❰ 'a ❱, ❰ 'b ❱, V, G, D>(bar: &'a str, baz: &'b mut str) {}
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/generics.html)
         struct LifetimeParam: AttrsOwner { T![lifetime] }
-        struct TypeBound { T![lifetime], /* Question,  */ T![const], /* Question,  */ TypeRef}
+
+        /// Type bound declaration clause.
+        ///
+        /// ```
+        /// fn foo<T: ❰ ?Sized ❱ + ❰ Debug ❱>() {}
+        ///
+        /// trait Bar<T>
+        /// where
+        ///     T: ❰ Send ❱ + ❰ Sync ❱
+        /// {
+        ///     type Baz: ❰ !Sync ❱ + ❰ Debug ❱ + ❰ ?const Add ❱;
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/trait-bounds.html)
+        struct TypeBound { T![lifetime], /* Question,  */ T![const], /* Question, */ TypeRef }
+
+        /// Type bounds list.
+        ///
+        /// ```
+        ///
+        /// fn foo<T: ❰ ?Sized + Debug ❱>() {}
+        ///
+        /// trait Bar<T>
+        /// where
+        ///     T: ❰ Send + Sync ❱
+        /// {
+        ///     type Baz: ❰ !Sync + Debug ❱;
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/trait-bounds.html)
         struct TypeBoundList { bounds: [TypeBound] }
+
+        /// Single where predicate.
+        ///
+        /// ```
+        /// trait Foo<'a, 'b, T>
+        /// where
+        ///     ❰ 'a: 'b ❱,
+        ///     ❰ T: IntoIterator ❱,
+        ///     ❰ for<'c> <T as IntoIterator>::Item: Bar<'c> ❱
+        /// {}
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/generics.html#where-clauses)
         struct WherePred: TypeBoundsOwner { T![lifetime], TypeRef }
+
+        /// Where clause.
+        ///
+        /// ```
+        /// trait Foo<'a, T> ❰ where 'a: 'static, T: Debug ❱ {}
+        ///
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/generics.html#where-clauses)
         struct WhereClause { T![where], predicates: [WherePred] }
+
+        /// Abi declaration.
+        /// Note: the abi string is optional.
+        ///
+        /// ```
+        /// ❰ extern "C" ❱ {
+        ///     fn foo() {}
+        /// }
+        ///
+        /// type Bar = ❰ extern ❱ fn() -> u32;
+        ///
+        /// type Baz = ❰ extern r#"stdcall"# ❱ fn() -> bool;
+        /// ```
+        ///
+        /// - [Extern blocks reference](https://doc.rust-lang.org/reference/items/external-blocks.html)
+        /// - [FFI function pointers reference](https://doc.rust-lang.org/reference/items/functions.html#functions)
         struct Abi { /*String*/ }
+
+        /// Expression statement.
+        ///
+        /// ```
+        /// ❰ 42; ❱
+        /// ❰ foo(); ❱
+        /// ❰ (); ❱
+        /// ❰ {}; ❱
+        ///
+        /// // constructions with trailing curly brace can omit the semicolon
+        /// // but only when there are satements immediately after them (this is important!)
+        /// ❰ if bool_cond { } ❱
+        /// ❰ loop {} ❱
+        /// ❰ somestatment; ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/statements.html)
         struct ExprStmt: AttrsOwner { Expr, T![;] }
+
+        /// Let statement.
+        ///
+        /// ```
+        /// ❰ #[attr] let foo; ❱
+        /// ❰ let bar: u64; ❱
+        /// ❰ let baz = 42; ❱
+        /// ❰ let bruh: bool = true; ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/statements.html#let-statements)
         struct LetStmt: AttrsOwner, TypeAscriptionOwner {
             T![let],
             Pat,
@@ -553,48 +1771,192 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             initializer: Expr,
             T![;],
         }
+
+        /// Condition of `if` or `while` expression.
+        ///
+        /// ```
+        /// if ❰ true ❱ {}
+        /// if ❰ let Pat(foo) = bar ❱ {}
+        ///
+        /// while ❰ true ❱ {}
+        /// while ❰ let Pat(baz) = bruh ❱ {}
+        /// ```
+        ///
+        /// [If expression reference](https://doc.rust-lang.org/reference/expressions/if-expr.html)
+        /// [While expression reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-loops)
         struct Condition { T![let], Pat, T![=], Expr }
-        struct Block: AttrsOwner, ModuleItemOwner {
-            T!['{'],
-            statements: [Stmt],
-            Expr,
-            T!['}'],
-        }
-        struct ParamList {
+
+        /// Parameter list **declaration**.
+        ///
+        /// ```
+        /// fn foo❰ (a: u32, b: bool) ❱ -> u32 {}
+        /// let bar = ❰ |a, b| ❱ {};
+        ///
+        /// impl Baz {
+        ///     fn bruh❰ (&self, a: u32) ❱ {}
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/functions.html)ocs to codegen script
+        struct ParamList { // FIXME: this node is used by closure expressions too, but hey use pipes instead of parens...
             T!['('],
             SelfParam,
             params: [Param],
             T![')']
         }
+
+        /// Self parameter **declaration**.
+        ///
+        /// ```
+        /// impl Bruh {
+        ///     fn foo(❰ self ❱) {}
+        ///     fn bar(❰ &self ❱) {}
+        ///     fn baz(❰ &mut self ❱) {}
+        ///     fn blah<'a>(❰ &'a self ❱) {}
+        ///     fn blin(❰ self: Box<Self> ❱) {}
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/functions.html)
         struct SelfParam: TypeAscriptionOwner, AttrsOwner { T![&], T![mut], T![lifetime], T![self] }
+
+        /// Parameter **declaration**.
+        ///
+        /// ```
+        /// fn foo(❰ #[attr] Pat(bar): Pat(u32) ❱, ❰ #[attr] _: bool ❱) {}
+        ///
+        /// extern "C" {
+        ///     fn bar(❰ baz: u32 ❱, ❰ ... ❱) -> u32;
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/functions.html)
         struct Param: TypeAscriptionOwner, AttrsOwner {
             Pat,
             T![...]
         }
+
+        /// Use declaration.
+        ///
+        /// ```
+        /// ❰ #[attr] pub use foo; ❱
+        /// ❰ use bar as baz; ❱
+        /// ❰ use bruh::{self, bruuh}; ❱
+        /// ❰ use { blin::blen, blah::* };
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/use-declarations.html)
         struct UseItem: AttrsOwner, VisibilityOwner {
             T![use],
             UseTree,
         }
+
+        /// Use tree.
+        ///
+        /// ```
+        /// pub use ❰ foo::❰ * ❱ ❱;
+        /// use ❰ bar as baz ❱;
+        /// use ❰ bruh::bruuh::{ ❰ self ❱, ❰ blin ❱ } ❱;
+        /// use ❰ { ❰ blin::blen ❱ } ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/use-declarations.html)
         struct UseTree {
             Path, T![*], UseTreeList, Alias
         }
+
+        /// Item alias.
+        /// Note: this is not the type alias.
+        ///
+        /// ```
+        /// use foo ❰ as bar ❱;
+        /// use baz::{bruh ❰ as _ ❱};
+        /// extern crate bruuh ❰ as blin ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/use-declarations.html)
         struct Alias: NameOwner { T![as] }
+
+        /// Sublist of use trees.
+        ///
+        /// ```
+        /// use bruh::bruuh::❰ { ❰ self ❱, ❰ blin ❱ } ❱;
+        /// use ❰ { blin::blen::❰ {} ❱ } ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/use-declarations.html)
         struct UseTreeList { T!['{'], use_trees: [UseTree], T!['}'] }
+
+        /// Extern crate item.
+        ///
+        /// ```
+        /// ❰ #[attr] pub extern crate foo; ❱
+        /// ❰ extern crate self as bar; ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/extern-crates.html)
         struct ExternCrateItem: AttrsOwner, VisibilityOwner {
             T![extern], T![crate], NameRef, Alias,
         }
+
+        /// Call site arguments list.
+        ///
+        /// ```
+        /// foo::<T, U>❰ (42, true) ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/expressions/call-expr.html)
         struct ArgList {
             T!['('],
             args: [Expr],
             T![')']
         }
+
+        /// Path to a symbol. Includes single identifier names and elaborate paths with
+        /// generic parameters.
+        ///
+        /// ```
+        /// (0..10).❰ ❰ collect ❱ ::<Vec<_>> ❱();
+        /// ❰ ❰ ❰ Vec ❱ ::<u8> ❱ ::with_capacity ❱(1024);
+        /// ❰ ❰ <❰ Foo ❱ as ❰ ❰ bar ❱ ::Bar ❱> ❱ ::baz ❱();
+        /// ❰ ❰ <❰ bruh ❱> ❱ ::bruuh ❱();
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/paths.html)
         struct Path {
             segment: PathSegment,
+            T![::],
             qualifier: Path,
         }
+
+        /// Segment of the path to a symbol.
+        /// Only path segment of an absolute path holds the `::` token,
+        /// all other `::` tokens that connect path segments reside under `Path` itself.`
+        ///
+        /// ```
+        /// (0..10).❰ collect ❱ :: ❰ <Vec<_>> ❱();
+        /// ❰ Vec ❱ :: ❰ <u8> ❱ :: ❰ with_capacity ❱(1024);
+        /// ❰ <❰ Foo ❱ as ❰ bar ❱ :: ❰ Bar ❱> ❱ :: ❰ baz ❱();
+        /// ❰ <❰ bruh ❱> ❱ :: ❰ bruuh ❱();
+        ///
+        /// // Note that only in this case `::` token is inlcuded:
+        /// ❰ ::foo ❱;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/paths.html)
         struct PathSegment {
-            T![::], T![crate], T![<], NameRef, TypeArgList, ParamList, RetType, PathType, T![>]
+            T![::], T![crate], T![self], T![super], T![<], NameRef, TypeArgList, ParamList, RetType, PathType, T![>]
         }
+
+        /// List of type arguments that are passed at generic instantiation site.
+        ///
+        /// ```
+        /// type _ = Foo ❰ ::<'a, u64, Item = Bar, 42, {true}> ❱::Bar;
+        ///
+        /// Vec❰ ::<bool> ❱::();
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/paths.html#paths-in-expressions)
         struct TypeArgList {
             T![::],
             T![<],
@@ -605,48 +1967,142 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             const_args: [ConstArg],
             T![>]
         }
+
+        /// Type argument that is passed at generic instantiation site.
+        ///
+        /// ```
+        /// type _ = Foo::<'a, ❰ u64 ❱, ❰ bool ❱, Item = Bar, 42>::Baz;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/paths.html#paths-in-expressions)
         struct TypeArg { TypeRef }
+
+        /// Associated type argument that is passed at generic instantiation site.
+        /// ```
+        /// type Foo = Bar::<'a, u64, bool, ❰ Item = Baz ❱, 42>::Bruh;
+        ///
+        /// trait Bruh<T>: Iterator<❰ Item: Debug ❱> {}
+        /// ```
+        ///
         struct AssocTypeArg : TypeBoundsOwner { NameRef, T![=], TypeRef }
+
+        /// Lifetime argument that is passed at generic instantiation site.
+        ///
+        /// ```
+        /// fn foo<'a>(s: &'a str) {
+        ///     bar::<❰ 'a ❱>(s);
+        /// }
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/paths.html#paths-in-expressions)
         struct LifetimeArg { T![lifetime] }
-        struct ConstArg { Literal, T![=], BlockExpr }
 
-        struct MacroItems: ModuleItemOwner{ }
+        /// Constant value argument that is passed at generic instantiation site.
+        ///
+        /// ```
+        /// foo::<u32, ❰ { true } ❱>();
+        ///
+        /// bar::<❰ { 2 + 2} ❱>();
+        /// ```
+        ///
+        /// [RFC](https://github.com/rust-lang/rfcs/blob/master/text/2000-const-generics.md#declaring-a-const-parameter)
+        struct ConstArg { Literal, BlockExpr }
+
+
+        /// FIXME: (@edwin0cheng) Remove it to use ItemList instead
+        /// https://github.com/rust-analyzer/rust-analyzer/pull/4083#discussion_r422666243
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/macros.html)
+        struct MacroItems: ModuleItemOwner { }
 
+        /// FIXME: (@edwin0cheng) add some documentation here. As per the writing
+        /// of this comment this ast node is not used.
+        ///
+        /// ```
+        /// // FIXME: example here
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/macros.html)
         struct MacroStmts {
             statements: [Stmt],
             Expr,
         }
 
+        /// List of items in an extern block.
+        ///
+        /// ```
+        /// extern "C" ❰
+        ///     {
+        ///         fn foo();
+        ///         static var: u32;
+        ///     }
+        /// ❱
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/external-blocks.html)
         struct ExternItemList: ModuleItemOwner {
             T!['{'],
             extern_items: [ExternItem],
             T!['}']
         }
 
+        /// Extern block.
+        ///
+        /// ```
+        /// ❰
+        ///     extern "C" {
+        ///         fn foo();
+        ///     }
+        /// ❱
+        ///
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/items/external-blocks.html)
         struct ExternBlock {
             Abi,
             ExternItemList
         }
 
+        /// Meta item in an attribute.
+        ///
+        /// ```
+        /// #[❰ bar::baz = "42" ❱]
+        /// #[❰ bruh(bruuh("true")) ❱]
+        /// struct Foo;
+        /// ```
+        ///
+        /// [Reference](https://doc.rust-lang.org/reference/attributes.html?highlight=meta,item#meta-item-attribute-syntax)
         struct MetaItem {
             Path, T![=], AttrInput, nested_meta_items: [MetaItem]
         }
 
+        /// Macro 2.0 definition.
+        /// Their syntax is still WIP by rustc team...
+        /// ```
+        /// ❰
+        ///     macro foo { }
+        /// ❱
+        /// ```
+        ///
+        /// [RFC](https://github.com/rust-lang/rfcs/blob/master/text/1584-macros.md)
         struct MacroDef {
             Name, TokenTree
         }
     },
     enums: &ast_enums! {
+        /// Any kind of nominal type definition.
         enum NominalDef: NameOwner, TypeParamsOwner, AttrsOwner {
             StructDef, EnumDef, UnionDef,
         }
 
+        /// Any kind of **declared** generic parameter
         enum GenericParam {
             LifetimeParam,
             TypeParam,
             ConstParam
         }
 
+        /// Any kind of generic argument passed at instantiation site
         enum GenericArg {
             LifetimeArg,
             TypeArg,
@@ -654,6 +2110,7 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             AssocTypeArg
         }
 
+        /// Any kind of construct valid in type context
         enum TypeRef {
             ParenType,
             TupleType,
@@ -670,6 +2127,7 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             DynTraitType,
         }
 
+        /// Any kind of top-level item that may appear in a module
         enum ModuleItem: NameOwner, AttrsOwner, VisibilityOwner {
             StructDef,
             UnionDef,
@@ -687,16 +2145,23 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             ExternBlock
         }
 
-        /* impl blocks can also contain MacroCall */
-        enum ImplItem: NameOwner, AttrsOwner {
+
+
+        /// Any kind of item that may appear in an impl block
+        ///
+        /// // FIXME: impl blocks can also contain MacroCall
+        enum AssocItem: NameOwner, AttrsOwner {
             FnDef, TypeAliasDef, ConstDef
         }
 
-        /* extern blocks can also contain MacroCall */
+        /// Any kind of item that may appear in an extern block
+        ///
+        /// // FIXME: extern blocks can also contain MacroCall
         enum ExternItem: NameOwner, AttrsOwner, VisibilityOwner {
             FnDef, StaticDef
         }
 
+        /// Any kind of expression
         enum Expr: AttrsOwner {
             TupleExpr,
             ArrayExpr,
@@ -720,6 +2185,7 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             FieldExpr,
             AwaitExpr,
             TryExpr,
+            EffectExpr,
             CastExpr,
             RefExpr,
             PrefixExpr,
@@ -730,6 +2196,7 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             BoxExpr,
         }
 
+        /// Any kind of pattern
         enum Pat {
             OrPat,
             ParenPat,
@@ -748,18 +2215,26 @@ pub(crate) const AST_SRC: AstSrc = AstSrc {
             MacroPat,
         }
 
+        /// Any kind of pattern that appears directly inside of the curly
+        /// braces of a record pattern
         enum RecordInnerPat {
             RecordFieldPat,
             BindPat
         }
 
+        /// Any kind of input to an attribute
         enum AttrInput { Literal, TokenTree }
+
+        /// Any kind of statement
+        /// Note: there are no empty statements, these are just represented as
+        /// bare semicolons without a dedicated statement ast node.
         enum Stmt {
             LetStmt,
             ExprStmt,
-            // macro calls are parsed as expression statements */
+            // macro calls are parsed as expression statements
         }
 
+        /// Any kind of fields list (record or tuple field lists)
         enum FieldDefList {
             RecordFieldDefList,
             TupleFieldDefList,
diff --git a/xtask/src/codegen.rs b/xtask/src/codegen.rs
index 0e4dcb95a..5511c01d5 100644
--- a/xtask/src/codegen.rs
+++ b/xtask/src/codegen.rs
@@ -8,14 +8,18 @@
 mod gen_syntax;
 mod gen_parser_tests;
 mod gen_assists_docs;
+mod gen_feature_docs;
 
-use std::{mem, path::Path};
+use std::{
+    fmt, mem,
+    path::{Path, PathBuf},
+};
 
-use crate::{not_bash::fs2, Result};
+use crate::{not_bash::fs2, project_root, Result};
 
 pub use self::{
-    gen_assists_docs::generate_assists_docs, gen_parser_tests::generate_parser_tests,
-    gen_syntax::generate_syntax,
+    gen_assists_docs::generate_assists_docs, gen_feature_docs::generate_feature_docs,
+    gen_parser_tests::generate_parser_tests, gen_syntax::generate_syntax,
 };
 
 const GRAMMAR_DIR: &str = "crates/ra_parser/src/grammar";
@@ -27,8 +31,7 @@ const AST_NODES: &str = "crates/ra_syntax/src/ast/generated/nodes.rs";
 const AST_TOKENS: &str = "crates/ra_syntax/src/ast/generated/tokens.rs";
 
 const ASSISTS_DIR: &str = "crates/ra_assists/src/handlers";
-const ASSISTS_TESTS: &str = "crates/ra_assists/src/doc_tests/generated.rs";
-const ASSISTS_DOCS: &str = "docs/user/assists.md";
+const ASSISTS_TESTS: &str = "crates/ra_assists/src/tests/generated.rs";
 
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum Mode {
@@ -40,7 +43,7 @@ pub enum Mode {
 /// With verify = false,
 fn update(path: &Path, contents: &str, mode: Mode) -> Result<()> {
     match fs2::read_to_string(path) {
-        Ok(ref old_contents) if normalize(old_contents) == normalize(contents) => {
+        Ok(old_contents) if normalize(&old_contents) == normalize(contents) => {
             return Ok(());
         }
         _ => (),
@@ -58,35 +61,85 @@ fn update(path: &Path, contents: &str, mode: Mode) -> Result<()> {
 }
 
 fn extract_comment_blocks(text: &str) -> Vec<Vec<String>> {
-    do_extract_comment_blocks(text, false)
+    do_extract_comment_blocks(text, false).into_iter().map(|(_line, block)| block).collect()
+}
+
+fn extract_comment_blocks_with_empty_lines(tag: &str, text: &str) -> Vec<CommentBlock> {
+    assert!(tag.starts_with(char::is_uppercase));
+    let tag = format!("{}:", tag);
+    let mut res = Vec::new();
+    for (line, mut block) in do_extract_comment_blocks(text, true) {
+        let first = block.remove(0);
+        if first.starts_with(&tag) {
+            let id = first[tag.len()..].trim().to_string();
+            let block = CommentBlock { id, line, contents: block };
+            res.push(block);
+        }
+    }
+    res
 }
 
-fn extract_comment_blocks_with_empty_lines(text: &str) -> Vec<Vec<String>> {
-    do_extract_comment_blocks(text, true)
+struct CommentBlock {
+    id: String,
+    line: usize,
+    contents: Vec<String>,
 }
 
-fn do_extract_comment_blocks(text: &str, allow_blocks_with_empty_lines: bool) -> Vec<Vec<String>> {
+fn do_extract_comment_blocks(
+    text: &str,
+    allow_blocks_with_empty_lines: bool,
+) -> Vec<(usize, Vec<String>)> {
     let mut res = Vec::new();
 
     let prefix = "// ";
     let lines = text.lines().map(str::trim_start);
 
-    let mut block = vec![];
-    for line in lines {
+    let mut block = (0, vec![]);
+    for (line_num, line) in lines.enumerate() {
         if line == "//" && allow_blocks_with_empty_lines {
-            block.push(String::new());
+            block.1.push(String::new());
             continue;
         }
 
         let is_comment = line.starts_with(prefix);
         if is_comment {
-            block.push(line[prefix.len()..].to_string());
-        } else if !block.is_empty() {
-            res.push(mem::replace(&mut block, Vec::new()));
+            block.1.push(line[prefix.len()..].to_string());
+        } else {
+            if !block.1.is_empty() {
+                res.push(mem::take(&mut block));
+            }
+            block.0 = line_num + 2;
         }
     }
-    if !block.is_empty() {
-        res.push(mem::replace(&mut block, Vec::new()))
+    if !block.1.is_empty() {
+        res.push(block)
     }
     res
 }
+
+#[derive(Debug)]
+struct Location {
+    file: PathBuf,
+    line: usize,
+}
+
+impl Location {
+    fn new(file: PathBuf, line: usize) -> Self {
+        Self { file, line }
+    }
+}
+
+impl fmt::Display for Location {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let path = self.file.strip_prefix(&project_root()).unwrap().display().to_string();
+        let path = path.replace('\\', "/");
+        let name = self.file.file_name().unwrap();
+        write!(
+            f,
+            "https://github.com/rust-analyzer/rust-analyzer/blob/master/{}#L{}[{}]",
+            path,
+            self.line,
+            name.to_str().unwrap()
+        )
+    }
+}
diff --git a/xtask/src/codegen/gen_assists_docs.rs b/xtask/src/codegen/gen_assists_docs.rs
index 31d606535..6c1be5350 100644
--- a/xtask/src/codegen/gen_assists_docs.rs
+++ b/xtask/src/codegen/gen_assists_docs.rs
@@ -1,114 +1,124 @@
 //! Generates `assists.md` documentation.
 
-use std::{fs, path::Path};
+use std::{fmt, fs, path::Path};
 
 use crate::{
-    codegen::{self, extract_comment_blocks_with_empty_lines, Mode},
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
     project_root, rust_files, Result,
 };
 
 pub fn generate_assists_docs(mode: Mode) -> Result<()> {
-    let assists = collect_assists()?;
+    let assists = Assist::collect()?;
     generate_tests(&assists, mode)?;
-    generate_docs(&assists, mode)?;
+
+    let contents = assists.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_assists.adoc");
+    codegen::update(&dst, &contents, mode)?;
+
     Ok(())
 }
 
 #[derive(Debug)]
 struct Assist {
     id: String,
+    location: Location,
     doc: String,
     before: String,
     after: String,
 }
 
-fn hide_hash_comments(text: &str) -> String {
-    text.split('\n') // want final newline
-        .filter(|&it| !(it.starts_with("# ") || it == "#"))
-        .map(|it| format!("{}\n", it))
-        .collect()
-}
-
-fn reveal_hash_comments(text: &str) -> String {
-    text.split('\n') // want final newline
-        .map(|it| {
-            if it.starts_with("# ") {
-                &it[2..]
-            } else if it == "#" {
-                ""
-            } else {
-                it
-            }
-        })
-        .map(|it| format!("{}\n", it))
-        .collect()
-}
-
-fn collect_assists() -> Result<Vec<Assist>> {
-    let mut res = Vec::new();
-    for path in rust_files(&project_root().join(codegen::ASSISTS_DIR)) {
-        collect_file(&mut res, path.as_path())?;
-    }
-    res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
-    return Ok(res);
-
-    fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
-        let text = fs::read_to_string(path)?;
-        let comment_blocks = extract_comment_blocks_with_empty_lines(&text);
-
-        for block in comment_blocks {
-            // FIXME: doesn't support blank lines yet, need to tweak
-            // `extract_comment_blocks` for that.
-            let mut lines = block.iter();
-            let first_line = lines.next().unwrap();
-            if !first_line.starts_with("Assist: ") {
-                continue;
-            }
-            let id = first_line["Assist: ".len()..].to_string();
-            assert!(
-                id.chars().all(|it| it.is_ascii_lowercase() || it == '_'),
-                "invalid assist id: {:?}",
-                id
-            );
-
-            let doc = take_until(lines.by_ref(), "```").trim().to_string();
-            assert!(
-                doc.chars().next().unwrap().is_ascii_uppercase() && doc.ends_with('.'),
-                "\n\n{}: assist docs should be proper sentences, with capitalization and a full stop at the end.\n\n{}\n\n",
-                id, doc,
-            );
-
-            let before = take_until(lines.by_ref(), "```");
-
-            assert_eq!(lines.next().unwrap().as_str(), "->");
-            assert_eq!(lines.next().unwrap().as_str(), "```");
-            let after = take_until(lines.by_ref(), "```");
-            acc.push(Assist { id, doc, before, after })
+impl Assist {
+    fn collect() -> Result<Vec<Assist>> {
+        let mut res = Vec::new();
+        for path in rust_files(&project_root().join(codegen::ASSISTS_DIR)) {
+            collect_file(&mut res, path.as_path())?;
         }
+        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
+        return Ok(res);
+
+        fn collect_file(acc: &mut Vec<Assist>, path: &Path) -> Result<()> {
+            let text = fs::read_to_string(path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Assist", &text);
+
+            for block in comment_blocks {
+                // FIXME: doesn't support blank lines yet, need to tweak
+                // `extract_comment_blocks` for that.
+                let id = block.id;
+                assert!(
+                    id.chars().all(|it| it.is_ascii_lowercase() || it == '_'),
+                    "invalid assist id: {:?}",
+                    id
+                );
+                let mut lines = block.contents.iter();
+
+                let doc = take_until(lines.by_ref(), "```").trim().to_string();
+                assert!(
+                    doc.chars().next().unwrap().is_ascii_uppercase() && doc.ends_with('.'),
+                    "\n\n{}: assist docs should be proper sentences, with capitalization and a full stop at the end.\n\n{}\n\n",
+                    id, doc,
+                );
+
+                let before = take_until(lines.by_ref(), "```");
+
+                assert_eq!(lines.next().unwrap().as_str(), "->");
+                assert_eq!(lines.next().unwrap().as_str(), "```");
+                let after = take_until(lines.by_ref(), "```");
+                let location = Location::new(path.to_path_buf(), block.line);
+                acc.push(Assist { id, location, doc, before, after })
+            }
 
-        fn take_until<'a>(lines: impl Iterator<Item = &'a String>, marker: &str) -> String {
-            let mut buf = Vec::new();
-            for line in lines {
-                if line == marker {
-                    break;
+            fn take_until<'a>(lines: impl Iterator<Item = &'a String>, marker: &str) -> String {
+                let mut buf = Vec::new();
+                for line in lines {
+                    if line == marker {
+                        break;
+                    }
+                    buf.push(line.clone());
                 }
-                buf.push(line.clone());
+                buf.join("\n")
             }
-            buf.join("\n")
+            Ok(())
         }
-        Ok(())
+    }
+}
+
+impl fmt::Display for Assist {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let before = self.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
+        let after = self.after.replace("<|>", "┃");
+        writeln!(
+            f,
+            "[discrete]\n=== `{}`
+**Source:** {}
+
+{}
+
+.Before
+```rust
+{}```
+
+.After
+```rust
+{}```",
+            self.id,
+            self.location,
+            self.doc,
+            hide_hash_comments(&before),
+            hide_hash_comments(&after)
+        )
     }
 }
 
 fn generate_tests(assists: &[Assist], mode: Mode) -> Result<()> {
-    let mut buf = String::from("use super::check;\n");
+    let mut buf = String::from("use super::check_doc_test;\n");
 
     for assist in assists.iter() {
         let test = format!(
             r######"
 #[test]
 fn doctest_{}() {{
-    check(
+    check_doc_test(
         "{}",
 r#####"
 {}"#####, r#####"
@@ -127,33 +137,24 @@ r#####"
     codegen::update(&project_root().join(codegen::ASSISTS_TESTS), &buf, mode)
 }
 
-fn generate_docs(assists: &[Assist], mode: Mode) -> Result<()> {
-    let mut buf = String::from(
-        "# Assists\n\nCursor position or selection is signified by `┃` character.\n\n",
-    );
-
-    for assist in assists {
-        let before = assist.before.replace("<|>", "┃"); // Unicode pseudo-graphics bar
-        let after = assist.after.replace("<|>", "┃");
-        let docs = format!(
-            "
-## `{}`
-
-{}
-
-```rust
-// BEFORE
-{}
-// AFTER
-{}```
-",
-            assist.id,
-            assist.doc,
-            hide_hash_comments(&before),
-            hide_hash_comments(&after)
-        );
-        buf.push_str(&docs);
-    }
+fn hide_hash_comments(text: &str) -> String {
+    text.split('\n') // want final newline
+        .filter(|&it| !(it.starts_with("# ") || it == "#"))
+        .map(|it| format!("{}\n", it))
+        .collect()
+}
 
-    codegen::update(&project_root().join(codegen::ASSISTS_DOCS), &buf, mode)
+fn reveal_hash_comments(text: &str) -> String {
+    text.split('\n') // want final newline
+        .map(|it| {
+            if it.starts_with("# ") {
+                &it[2..]
+            } else if it == "#" {
+                ""
+            } else {
+                it
+            }
+        })
+        .map(|it| format!("{}\n", it))
+        .collect()
 }
diff --git a/xtask/src/codegen/gen_feature_docs.rs b/xtask/src/codegen/gen_feature_docs.rs
new file mode 100644
index 000000000..31bc3839d
--- /dev/null
+++ b/xtask/src/codegen/gen_feature_docs.rs
@@ -0,0 +1,75 @@
+//! Generates `assists.md` documentation.
+
+use std::{fmt, fs, path::PathBuf};
+
+use crate::{
+    codegen::{self, extract_comment_blocks_with_empty_lines, Location, Mode},
+    project_root, rust_files, Result,
+};
+
+pub fn generate_feature_docs(mode: Mode) -> Result<()> {
+    let features = Feature::collect()?;
+    let contents = features.into_iter().map(|it| it.to_string()).collect::<Vec<_>>().join("\n\n");
+    let contents = contents.trim().to_string() + "\n";
+    let dst = project_root().join("docs/user/generated_features.adoc");
+    codegen::update(&dst, &contents, mode)?;
+    Ok(())
+}
+
+#[derive(Debug)]
+struct Feature {
+    id: String,
+    location: Location,
+    doc: String,
+}
+
+impl Feature {
+    fn collect() -> Result<Vec<Feature>> {
+        let mut res = Vec::new();
+        for path in rust_files(&project_root()) {
+            collect_file(&mut res, path)?;
+        }
+        res.sort_by(|lhs, rhs| lhs.id.cmp(&rhs.id));
+        return Ok(res);
+
+        fn collect_file(acc: &mut Vec<Feature>, path: PathBuf) -> Result<()> {
+            let text = fs::read_to_string(&path)?;
+            let comment_blocks = extract_comment_blocks_with_empty_lines("Feature", &text);
+
+            for block in comment_blocks {
+                let id = block.id;
+                assert!(is_valid_feature_name(&id), "invalid feature name: {:?}", id);
+                let doc = block.contents.join("\n");
+                let location = Location::new(path.clone(), block.line);
+                acc.push(Feature { id, location, doc })
+            }
+
+            Ok(())
+        }
+    }
+}
+
+fn is_valid_feature_name(feature: &str) -> bool {
+    'word: for word in feature.split_whitespace() {
+        for &short in ["to", "and"].iter() {
+            if word == short {
+                continue 'word;
+            }
+        }
+        for &short in ["To", "And"].iter() {
+            if word == short {
+                return false;
+            }
+        }
+        if !word.starts_with(char::is_uppercase) {
+            return false;
+        }
+    }
+    true
+}
+
+impl fmt::Display for Feature {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        writeln!(f, "=== {}\n**Source:** {}\n{}", self.id, self.location, self.doc)
+    }
+}
diff --git a/xtask/src/codegen/gen_syntax.rs b/xtask/src/codegen/gen_syntax.rs
index e9dc09552..19d5594f5 100644
--- a/xtask/src/codegen/gen_syntax.rs
+++ b/xtask/src/codegen/gen_syntax.rs
@@ -3,7 +3,7 @@
 //! Specifically, it generates the `SyntaxKind` enum and a number of newtype
 //! wrappers around `SyntaxNode` which implement `ra_syntax::AstNode`.
 
-use std::collections::HashSet;
+use std::{collections::HashSet, fmt::Write};
 
 use proc_macro2::{Punct, Spacing};
 use quote::{format_ident, quote};
@@ -102,6 +102,7 @@ fn generate_nodes(kinds: KindsSrc<'_>, grammar: AstSrc<'_>) -> Result<String> {
             });
             (
                 quote! {
+                    #[pretty_doc_comment_placeholder_workaround]
                     #[derive(Debug, Clone, PartialEq, Eq, Hash)]
                     pub struct #name {
                         pub(crate) syntax: SyntaxNode,
@@ -145,6 +146,7 @@ fn generate_nodes(kinds: KindsSrc<'_>, grammar: AstSrc<'_>) -> Result<String> {
 
             (
                 quote! {
+                    #[pretty_doc_comment_placeholder_workaround]
                     #[derive(Debug, Clone, PartialEq, Eq, Hash)]
                     pub enum #name {
                         #(#variants(#variants),)*
@@ -230,10 +232,29 @@ fn generate_nodes(kinds: KindsSrc<'_>, grammar: AstSrc<'_>) -> Result<String> {
     };
 
     let ast = ast.to_string().replace("T ! [ ", "T![").replace(" ] )", "])");
-    let pretty = crate::reformat(ast)?.replace("#[derive", "\n#[derive");
+
+    let mut res = String::with_capacity(ast.len() * 2);
+
+    let mut docs =
+        grammar.nodes.iter().map(|it| it.doc).chain(grammar.enums.iter().map(|it| it.doc));
+
+    for chunk in ast.split("# [ pretty_doc_comment_placeholder_workaround ]") {
+        res.push_str(chunk);
+        if let Some(doc) = docs.next() {
+            write_doc_comment(doc, &mut res);
+        }
+    }
+
+    let pretty = crate::reformat(res)?;
     Ok(pretty)
 }
 
+fn write_doc_comment(contents: &[&str], dest: &mut String) {
+    for line in contents {
+        writeln!(dest, "///{}", line).unwrap();
+    }
+}
+
 fn generate_syntax_kinds(grammar: KindsSrc<'_>) -> Result<String> {
     let (single_byte_tokens_values, single_byte_tokens): (Vec<_>, Vec<_>) = grammar
         .punct
@@ -432,6 +453,7 @@ impl Field<'_> {
                     ":" => "colon",
                     "::" => "coloncolon",
                     "#" => "pound",
+                    "?" => "question_mark",
                     _ => name,
                 };
                 format_ident!("{}_token", name)
diff --git a/xtask/src/lib.rs b/xtask/src/lib.rs
index 2b7a461e5..874957885 100644
--- a/xtask/src/lib.rs
+++ b/xtask/src/lib.rs
@@ -191,7 +191,11 @@ Release: release:{}[]
     let path = changelog_dir.join(format!("{}-changelog-{}.adoc", today, changelog_n));
     fs2::write(&path, &contents)?;
 
-    fs2::copy(project_root().join("./docs/user/readme.adoc"), website_root.join("manual.adoc"))?;
+    for &adoc in ["manual.adoc", "generated_features.adoc", "generated_assists.adoc"].iter() {
+        let src = project_root().join("./docs/user/").join(adoc);
+        let dst = website_root.join(adoc);
+        fs2::copy(src, dst)?;
+    }
 
     let tags = run!("git tag --list"; echo = false)?;
     let prev_tag = tags.lines().filter(|line| is_release_tag(line)).last().unwrap();
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index dff3ce4a1..9d7cdd114 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -75,6 +75,7 @@ FLAGS:
             codegen::generate_syntax(Mode::Overwrite)?;
             codegen::generate_parser_tests(Mode::Overwrite)?;
             codegen::generate_assists_docs(Mode::Overwrite)?;
+            codegen::generate_feature_docs(Mode::Overwrite)?;
             Ok(())
         }
         "format" => {
diff --git a/xtask/tests/tidy-tests/cli.rs b/xtask/tests/tidy-tests/cli.rs
deleted file mode 100644
index f5b00a8b8..000000000
--- a/xtask/tests/tidy-tests/cli.rs
+++ /dev/null
@@ -1,32 +0,0 @@
-use xtask::{
-    codegen::{self, Mode},
-    run_rustfmt,
-};
-
-#[test]
-fn generated_grammar_is_fresh() {
-    if let Err(error) = codegen::generate_syntax(Mode::Verify) {
-        panic!("{}. Please update it by running `cargo xtask codegen`", error);
-    }
-}
-
-#[test]
-fn generated_tests_are_fresh() {
-    if let Err(error) = codegen::generate_parser_tests(Mode::Verify) {
-        panic!("{}. Please update tests by running `cargo xtask codegen`", error);
-    }
-}
-
-#[test]
-fn generated_assists_are_fresh() {
-    if let Err(error) = codegen::generate_assists_docs(Mode::Verify) {
-        panic!("{}. Please update assists by running `cargo xtask codegen`", error);
-    }
-}
-
-#[test]
-fn check_code_formatting() {
-    if let Err(error) = run_rustfmt(Mode::Verify) {
-        panic!("{}. Please format the code by running `cargo format`", error);
-    }
-}
diff --git a/xtask/tests/tidy-tests/main.rs b/xtask/tests/tidy.rs
index ead642acc..62626064e 100644
--- a/xtask/tests/tidy-tests/main.rs
+++ b/xtask/tests/tidy.rs
@@ -1,11 +1,48 @@
-mod cli;
-
 use std::{
     collections::HashMap,
     path::{Path, PathBuf},
 };
 
-use xtask::{not_bash::fs2, project_root, rust_files};
+use xtask::{
+    codegen::{self, Mode},
+    not_bash::fs2,
+    project_root, run_rustfmt, rust_files,
+};
+
+#[test]
+fn generated_grammar_is_fresh() {
+    if let Err(error) = codegen::generate_syntax(Mode::Verify) {
+        panic!("{}. Please update it by running `cargo xtask codegen`", error);
+    }
+}
+
+#[test]
+fn generated_tests_are_fresh() {
+    if let Err(error) = codegen::generate_parser_tests(Mode::Verify) {
+        panic!("{}. Please update tests by running `cargo xtask codegen`", error);
+    }
+}
+
+#[test]
+fn generated_assists_are_fresh() {
+    if let Err(error) = codegen::generate_assists_docs(Mode::Verify) {
+        panic!("{}. Please update assists by running `cargo xtask codegen`", error);
+    }
+}
+
+#[test]
+fn generated_features_are_fresh() {
+    if let Err(error) = codegen::generate_feature_docs(Mode::Verify) {
+        panic!("{}. Please update features by running `cargo xtask codegen`", error);
+    }
+}
+
+#[test]
+fn check_code_formatting() {
+    if let Err(error) = run_rustfmt(Mode::Verify) {
+        panic!("{}. Please format the code by running `cargo format`", error);
+    }
+}
 
 #[test]
 fn rust_files_are_tidy() {
@@ -24,9 +61,10 @@ fn check_todo(path: &Path, text: &str) {
         // This file itself is whitelisted since this test itself contains matches.
         "tests/cli.rs",
         // Some of our assists generate `todo!()` so those files are whitelisted.
-        "doc_tests/generated.rs",
+        "tests/generated.rs",
         "handlers/add_missing_impl_members.rs",
         "handlers/add_function.rs",
+        "handlers/add_turbo_fish.rs",
         // To support generating `todo!()` in assists, we have `expr_todo()` in ast::make.
         "ast/make.rs",
     ];
@@ -64,7 +102,7 @@ impl TidyDocs {
     fn visit(&mut self, path: &Path, text: &str) {
         // Test hopefully don't really need comments, and for assists we already
         // have special comments which are source of doc tests and user docs.
-        if is_exclude_dir(path, &["tests", "test_data", "handlers"]) {
+        if is_exclude_dir(path, &["tests", "test_data"]) {
             return;
         }
 
@@ -79,9 +117,12 @@ impl TidyDocs {
 
         if first_line.starts_with("//!") {
             if first_line.contains("FIXME") {
-                self.contains_fixme.push(path.to_path_buf())
+                self.contains_fixme.push(path.to_path_buf());
             }
         } else {
+            if text.contains("// Feature:") || text.contains("// Assist:") {
+                return;
+            }
             self.missing_docs.push(path.display().to_string());
         }
 
@@ -106,7 +147,6 @@ impl TidyDocs {
         }
 
         let whitelist = [
-            "ra_db",
             "ra_hir",
             "ra_hir_expand",
             "ra_ide",
@@ -115,7 +155,6 @@ impl TidyDocs {
             "ra_prof",
             "ra_project_model",
             "ra_syntax",
-            "ra_text_edit",
             "ra_tt",
             "ra_hir_ty",
         ];
@@ -141,13 +180,11 @@ impl TidyDocs {
 }
 
 fn is_exclude_dir(p: &Path, dirs_to_exclude: &[&str]) -> bool {
-    let mut cur_path = p;
-    while let Some(path) = cur_path.parent() {
-        if dirs_to_exclude.iter().any(|dir| path.ends_with(dir)) {
-            return true;
-        }
-        cur_path = path;
-    }
-
-    false
+    p.strip_prefix(project_root())
+        .unwrap()
+        .components()
+        .rev()
+        .skip(1)
+        .filter_map(|it| it.as_os_str().to_str())
+        .any(|it| dirs_to_exclude.contains(&it))
 }