Merge #4083

4083: Smol documentation for ast nodes r=matklad a=Veetaha

There is a tremendous amount of TODOs to clarify the topics I am not certain about.
Please @matklad, @edwin0cheng review carefully, I even left some mentions of your names in todos to put your attention where you most probably can give comments.

In order to simplify the review, I separated the codegen (i.e. changes in `ast/generated/nodes.rs`) from `ast_src` changes (they in fact just duplicate one another) into two commits.

Also, I had to hack a little bit to let the docs be generated as doc comments and not as doc attributes because it's easier to read them this way and IIRC we don't support hints for `#[doc = ""]` attributes for now...

Closes #3682 

Co-authored-by: veetaha <[email protected]>

1 files changed, 1366 insertions, 138 deletions

diff --git a/crates/ra_syntax/src/ast/generated/nodes.rs b/crates/ra_syntax/src/ast/generated/nodes.rs
index b00c15608..cf6067e57 100644
--- a/crates/ra_syntax/src/ast/generated/nodes.rs
+++ b/crates/ra_syntax/src/ast/generated/nodes.rs
@@ -5,7 +5,9 @@ use crate::{
     SyntaxKind::{self, *},
     SyntaxNode, SyntaxToken, T,
 };
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct SourceFile {
     pub(crate) syntax: SyntaxNode,
@@ -16,7 +18,28 @@ impl ast::DocCommentsOwner for SourceFile {}
 impl SourceFile {
     pub fn modules(&self) -> AstChildren<Module> { support::children(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct FnDef {
     pub(crate) syntax: SyntaxNode,
@@ -38,7 +61,13 @@ impl FnDef {
     pub fn body(&self) -> Option<BlockExpr> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![;]) }
 }
-
+/// Return type annotation.
+///
+/// ```
+/// fn foo(a: u32) ❰ -> Option<u32> ❱ { Some(a) }
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/items/functions.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RetType {
     pub(crate) syntax: SyntaxNode,
@@ -47,7 +76,26 @@ impl RetType {
     pub fn thin_arrow_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![->]) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct StructDef {
     pub(crate) syntax: SyntaxNode,
@@ -62,7 +110,23 @@ impl StructDef {
     pub fn field_def_list(&self) -> Option<FieldDefList> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct UnionDef {
     pub(crate) syntax: SyntaxNode,
@@ -78,7 +142,19 @@ impl UnionDef {
         support::child(&self.syntax)
     }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordFieldDefList {
     pub(crate) syntax: SyntaxNode,
@@ -88,7 +164,22 @@ impl RecordFieldDefList {
     pub fn fields(&self) -> AstChildren<RecordFieldDef> { support::children(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordFieldDef {
     pub(crate) syntax: SyntaxNode,
@@ -99,7 +190,13 @@ impl ast::AttrsOwner for RecordFieldDef {}
 impl ast::DocCommentsOwner for RecordFieldDef {}
 impl ast::TypeAscriptionOwner for RecordFieldDef {}
 impl RecordFieldDef {}
-
+/// Tuple field definition list including enclosing parens.
+///
+/// ```
+/// struct Foo ❰ (u32, String, Vec<u32>) ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TupleFieldDefList {
     pub(crate) syntax: SyntaxNode,
@@ -109,7 +206,13 @@ impl TupleFieldDefList {
     pub fn fields(&self) -> AstChildren<TupleFieldDef> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![')']) }
 }
-
+/// Tuple field definition including its attributes.
+///
+/// ```
+/// struct Foo(❰ #[attr] u32 ❱);
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/items/structs.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TupleFieldDef {
     pub(crate) syntax: SyntaxNode,
@@ -119,7 +222,29 @@ impl ast::AttrsOwner for TupleFieldDef {}
 impl TupleFieldDef {
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct EnumDef {
     pub(crate) syntax: SyntaxNode,
@@ -133,7 +258,22 @@ impl EnumDef {
     pub fn enum_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![enum]) }
     pub fn variant_list(&self) -> Option<EnumVariantList> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct EnumVariantList {
     pub(crate) syntax: SyntaxNode,
@@ -143,7 +283,21 @@ impl EnumVariantList {
     pub fn variants(&self) -> AstChildren<EnumVariant> { support::children(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct EnumVariant {
     pub(crate) syntax: SyntaxNode,
@@ -157,7 +311,20 @@ impl EnumVariant {
     pub fn eq_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TraitDef {
     pub(crate) syntax: SyntaxNode,
@@ -174,7 +341,27 @@ impl TraitDef {
     pub fn trait_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![trait]) }
     pub fn item_list(&self) -> Option<ItemList> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Module {
     pub(crate) syntax: SyntaxNode,
@@ -188,7 +375,28 @@ impl Module {
     pub fn item_list(&self) -> Option<ItemList> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ItemList {
     pub(crate) syntax: SyntaxNode,
@@ -199,7 +407,18 @@ impl ItemList {
     pub fn assoc_items(&self) -> AstChildren<AssocItem> { support::children(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ConstDef {
     pub(crate) syntax: SyntaxNode,
@@ -217,7 +436,18 @@ impl ConstDef {
     pub fn body(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct StaticDef {
     pub(crate) syntax: SyntaxNode,
@@ -235,7 +465,24 @@ impl StaticDef {
     pub fn body(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeAliasDef {
     pub(crate) syntax: SyntaxNode,
@@ -253,7 +500,20 @@ impl TypeAliasDef {
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![;]) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ImplDef {
     pub(crate) syntax: SyntaxNode,
@@ -270,7 +530,16 @@ impl ImplDef {
     pub fn for_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![for]) }
     pub fn item_list(&self) -> Option<ItemList> { support::child(&self.syntax) }
 }
-
+/// 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";
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ParenType {
     pub(crate) syntax: SyntaxNode,
@@ -280,7 +549,13 @@ impl ParenType {
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![')']) }
 }
-
+/// Unnamed tuple type.
+///
+/// ```
+/// let foo: ❰ (u32, bool) ❱ = (42, true);
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/tuple.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TupleType {
     pub(crate) syntax: SyntaxNode,
@@ -290,7 +565,17 @@ impl TupleType {
     pub fn fields(&self) -> AstChildren<TypeRef> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct NeverType {
     pub(crate) syntax: SyntaxNode,
@@ -298,7 +583,17 @@ pub struct NeverType {
 impl NeverType {
     pub fn excl_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PathType {
     pub(crate) syntax: SyntaxNode,
@@ -306,7 +601,14 @@ pub struct PathType {
 impl PathType {
     pub fn path(&self) -> Option<Path> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PointerType {
     pub(crate) syntax: SyntaxNode,
@@ -317,7 +619,13 @@ impl PointerType {
     pub fn mut_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![mut]) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// Array type.
+///
+/// ```
+/// type Foo = ❰ [u32; 24 - 3] ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/array.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ArrayType {
     pub(crate) syntax: SyntaxNode,
@@ -329,7 +637,13 @@ impl ArrayType {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn r_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![']']) }
 }
-
+/// Slice type.
+///
+/// ```
+/// type Foo = ❰ [u8] ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/slice.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct SliceType {
     pub(crate) syntax: SyntaxNode,
@@ -339,7 +653,13 @@ impl SliceType {
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
     pub fn r_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![']']) }
 }
-
+/// Reference type.
+///
+/// ```
+/// type Foo = ❰ &'static str ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/pointer.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ReferenceType {
     pub(crate) syntax: SyntaxNode,
@@ -352,7 +672,13 @@ impl ReferenceType {
     pub fn mut_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![mut]) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// Placeholder type (i.e. the underscore).
+///
+/// ```
+/// let foo: ❰ _ ❱ = 42_u32;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/inferred.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PlaceholderType {
     pub(crate) syntax: SyntaxNode,
@@ -360,7 +686,15 @@ pub struct PlaceholderType {
 impl PlaceholderType {
     pub fn underscore_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct FnPointerType {
     pub(crate) syntax: SyntaxNode,
@@ -372,7 +706,13 @@ impl FnPointerType {
     pub fn param_list(&self) -> Option<ParamList> { support::child(&self.syntax) }
     pub fn ret_type(&self) -> Option<RetType> { support::child(&self.syntax) }
 }
-
+/// Higher order type.
+///
+/// ```
+/// type Foo = ❰ for<'a> fn(&'a str) ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/nomicon/hrtb.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ForType {
     pub(crate) syntax: SyntaxNode,
@@ -382,7 +722,13 @@ impl ForType {
     pub fn type_param_list(&self) -> Option<TypeParamList> { support::child(&self.syntax) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// Opaque `impl Trait` type.
+///
+/// ```
+/// fn foo(bar: ❰ impl Debug + Eq ❱) {}
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/impl-trait.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ImplTraitType {
     pub(crate) syntax: SyntaxNode,
@@ -391,7 +737,13 @@ impl ast::TypeBoundsOwner for ImplTraitType {}
 impl ImplTraitType {
     pub fn impl_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![impl]) }
 }
-
+/// Trait object type.
+///
+/// ```
+/// type Foo = ❰ dyn Debug ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/types/trait-object.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct DynTraitType {
     pub(crate) syntax: SyntaxNode,
@@ -400,7 +752,13 @@ impl ast::TypeBoundsOwner for DynTraitType {}
 impl DynTraitType {
     pub fn dyn_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![dyn]) }
 }
-
+/// Tuple literal.
+///
+/// ```
+/// ❰ (42, true) ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/tuple-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TupleExpr {
     pub(crate) syntax: SyntaxNode,
@@ -411,7 +769,15 @@ impl TupleExpr {
     pub fn exprs(&self) -> AstChildren<Expr> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![')']) }
 }
-
+/// Array literal.
+///
+/// ```
+/// ❰ [#![inner_attr] true, false, true] ❱;
+///
+/// ❰ ["baz"; 24] ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/array-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ArrayExpr {
     pub(crate) syntax: SyntaxNode,
@@ -423,7 +789,14 @@ impl ArrayExpr {
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![;]) }
     pub fn r_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ParenExpr {
     pub(crate) syntax: SyntaxNode,
@@ -434,7 +807,19 @@ impl ParenExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![')']) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PathExpr {
     pub(crate) syntax: SyntaxNode,
@@ -442,7 +827,17 @@ pub struct PathExpr {
 impl PathExpr {
     pub fn path(&self) -> Option<Path> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LambdaExpr {
     pub(crate) syntax: SyntaxNode,
@@ -456,7 +851,25 @@ impl LambdaExpr {
     pub fn ret_type(&self) -> Option<RetType> { support::child(&self.syntax) }
     pub fn body(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct IfExpr {
     pub(crate) syntax: SyntaxNode,
@@ -466,7 +879,17 @@ impl IfExpr {
     pub fn if_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![if]) }
     pub fn condition(&self) -> Option<Condition> { support::child(&self.syntax) }
 }
-
+/// Unconditional loop expression.
+///
+/// ```
+/// ❰
+///     loop {
+///         // yeah, it's that simple...
+///     }
+/// ❱
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LoopExpr {
     pub(crate) syntax: SyntaxNode,
@@ -476,7 +899,20 @@ impl ast::LoopBodyOwner for LoopExpr {}
 impl LoopExpr {
     pub fn loop_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct EffectExpr {
     pub(crate) syntax: SyntaxNode,
@@ -489,7 +925,19 @@ impl EffectExpr {
     pub fn async_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![async]) }
     pub fn block_expr(&self) -> Option<BlockExpr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ForExpr {
     pub(crate) syntax: SyntaxNode,
@@ -502,7 +950,22 @@ impl ForExpr {
     pub fn in_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![in]) }
     pub fn iterable(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct WhileExpr {
     pub(crate) syntax: SyntaxNode,
@@ -513,7 +976,22 @@ impl WhileExpr {
     pub fn while_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![while]) }
     pub fn condition(&self) -> Option<Condition> { support::child(&self.syntax) }
 }
-
+/// Continue expression.
+///
+/// ```
+/// while bool_cond {
+///     ❰ continue ❱;
+/// }
+///
+/// 'outer: loop {
+///     loop {
+///         ❰ continue 'outer ❱;
+///     }
+/// }
+///
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/loop-expr.html#continue-expressions)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ContinueExpr {
     pub(crate) syntax: SyntaxNode,
@@ -527,7 +1005,25 @@ impl ContinueExpr {
         support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BreakExpr {
     pub(crate) syntax: SyntaxNode,
@@ -540,7 +1036,20 @@ impl BreakExpr {
     }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Label {
     pub(crate) syntax: SyntaxNode,
@@ -550,7 +1059,21 @@ impl Label {
         support::token(&self.syntax, T![lifetime])
     }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BlockExpr {
     pub(crate) syntax: SyntaxNode,
@@ -563,7 +1086,17 @@ impl BlockExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T!['}']) }
 }
-
+/// Return expression.
+///
+/// ```
+/// || ❰ return 42 ❱;
+///
+/// fn bar() {
+///     ❰ return ❱;
+/// }
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/return-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ReturnExpr {
     pub(crate) syntax: SyntaxNode,
@@ -572,7 +1105,16 @@ impl ast::AttrsOwner for ReturnExpr {}
 impl ReturnExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct CallExpr {
     pub(crate) syntax: SyntaxNode,
@@ -581,7 +1123,16 @@ impl ast::ArgListOwner for CallExpr {}
 impl CallExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MethodCallExpr {
     pub(crate) syntax: SyntaxNode,
@@ -594,7 +1145,13 @@ impl MethodCallExpr {
     pub fn name_ref(&self) -> Option<NameRef> { support::child(&self.syntax) }
     pub fn type_arg_list(&self) -> Option<TypeArgList> { support::child(&self.syntax) }
 }
-
+/// Index expression a.k.a. subscript operator call.
+///
+/// ```
+/// ❰ foo[42] ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/array-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct IndexExpr {
     pub(crate) syntax: SyntaxNode,
@@ -604,7 +1161,15 @@ impl IndexExpr {
     pub fn l_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T!['[']) }
     pub fn r_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![']']) }
 }
-
+/// Field access expression.
+///
+/// ```
+/// ❰ expr.bar ❱;
+///
+/// ❰ ❰ ❰ foo.bar ❱ .baz ❱ .bruh ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/field-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct FieldExpr {
     pub(crate) syntax: SyntaxNode,
@@ -615,7 +1180,13 @@ impl FieldExpr {
     pub fn dot_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![.]) }
     pub fn name_ref(&self) -> Option<NameRef> { support::child(&self.syntax) }
 }
-
+/// Await operator call expression.
+///
+/// ```
+/// ❰ expr.await ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/await-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct AwaitExpr {
     pub(crate) syntax: SyntaxNode,
@@ -626,7 +1197,13 @@ impl AwaitExpr {
     pub fn dot_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![.]) }
     pub fn await_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![await]) }
 }
-
+/// The question mark operator call.
+///
+/// ```
+/// ❰ expr? ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TryExpr {
     pub(crate) syntax: SyntaxNode,
@@ -636,7 +1213,13 @@ impl TryExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn question_mark_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![?]) }
 }
-
+/// Type cast expression.
+///
+/// ```
+/// ❰ expr as T ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#type-cast-expressions)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct CastExpr {
     pub(crate) syntax: SyntaxNode,
@@ -647,7 +1230,14 @@ impl CastExpr {
     pub fn as_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![as]) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// Borrow operator call.
+///
+/// ```
+/// ❰ &foo ❱;
+/// ❰ &mut bar ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#borrow-operators)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RefExpr {
     pub(crate) syntax: SyntaxNode,
@@ -659,7 +1249,15 @@ impl RefExpr {
     pub fn mut_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![mut]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// Prefix operator call. This is either `!` or `*` or `-`.
+///
+/// ```
+/// ❰ !foo ❱;
+/// ❰ *bar ❱;
+/// ❰ -42 ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PrefixExpr {
     pub(crate) syntax: SyntaxNode,
@@ -668,7 +1266,13 @@ impl ast::AttrsOwner for PrefixExpr {}
 impl PrefixExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// Box operator call.
+///
+/// ```
+/// ❰ box 42 ❱;
+/// ```
+///
+/// [RFC](https://github.com/rust-lang/rfcs/blob/0806be4f282144cfcd55b1d20284b43f87cbe1c6/text/0809-box-and-in-for-stdlib.md)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BoxExpr {
     pub(crate) syntax: SyntaxNode,
@@ -678,27 +1282,69 @@ impl BoxExpr {
     pub fn box_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![box]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// Range operator call.
+///
+/// ```
+/// ❰ 0..42 ❱;
+/// ❰ ..42 ❱;
+/// ❰ 0.. ❱;
+/// ❰ .. ❱;
+/// ❰ 0..=42 ❱;
+/// ❰ ..=42 ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/range-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RangeExpr {
     pub(crate) syntax: SyntaxNode,
 }
 impl ast::AttrsOwner for RangeExpr {}
 impl RangeExpr {}
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BinExpr {
     pub(crate) syntax: SyntaxNode,
 }
 impl ast::AttrsOwner for BinExpr {}
 impl BinExpr {}
-
+/// [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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Literal {
     pub(crate) syntax: SyntaxNode,
 }
 impl Literal {}
-
+/// Match expression.
+///
+/// ```
+/// ❰
+///     match expr {
+///         Pat1 => {}
+///         Pat2(_) => 42,
+///     }
+/// ❱
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/match-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MatchExpr {
     pub(crate) syntax: SyntaxNode,
@@ -709,7 +1355,20 @@ impl MatchExpr {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn match_arm_list(&self) -> Option<MatchArmList> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MatchArmList {
     pub(crate) syntax: SyntaxNode,
@@ -720,7 +1379,16 @@ impl MatchArmList {
     pub fn arms(&self) -> AstChildren<MatchArm> { support::children(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MatchArm {
     pub(crate) syntax: SyntaxNode,
@@ -732,7 +1400,15 @@ impl MatchArm {
     pub fn fat_arrow_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=>]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// Match guard.
+///
+/// ```
+/// match expr {
+///     Pattern(it) ❰ if bool_cond ❱ => it,
+/// }
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/match-expr.html#match-guards)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MatchGuard {
     pub(crate) syntax: SyntaxNode,
@@ -741,7 +1417,21 @@ impl MatchGuard {
     pub fn if_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![if]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordLit {
     pub(crate) syntax: SyntaxNode,
@@ -750,7 +1440,16 @@ impl RecordLit {
     pub fn path(&self) -> Option<Path> { support::child(&self.syntax) }
     pub fn record_field_list(&self) -> Option<RecordFieldList> { support::child(&self.syntax) }
 }
-
+/// Record field list including enclosing curly braces.
+///
+/// foo::Bar ❰
+///     {
+///         baz: 42,
+///         ..spread
+///     }
+/// ❱
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/struct-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordFieldList {
     pub(crate) syntax: SyntaxNode,
@@ -762,7 +1461,15 @@ impl RecordFieldList {
     pub fn spread(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T!['}']) }
 }
-
+/// Record field.
+///
+/// ```
+/// foo::Bar {
+///     ❰ #[attr] baz: 42 ❱
+/// }
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/struct-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordField {
     pub(crate) syntax: SyntaxNode,
@@ -773,7 +1480,13 @@ impl RecordField {
     pub fn colon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![:]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// Disjunction of patterns.
+///
+/// ```
+/// let ❰ Foo(it) | Bar(it) | Baz(it) ❱ = bruh;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct OrPat {
     pub(crate) syntax: SyntaxNode,
@@ -781,7 +1494,14 @@ pub struct OrPat {
 impl OrPat {
     pub fn pats(&self) -> AstChildren<Pat> { support::children(&self.syntax) }
 }
-
+/// 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
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ParenPat {
     pub(crate) syntax: SyntaxNode,
@@ -791,7 +1511,16 @@ impl ParenPat {
     pub fn pat(&self) -> Option<Pat> { support::child(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RefPat {
     pub(crate) syntax: SyntaxNode,
@@ -801,7 +1530,13 @@ impl RefPat {
     pub fn mut_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![mut]) }
     pub fn pat(&self) -> Option<Pat> { support::child(&self.syntax) }
 }
-
+/// Box pattern.
+///
+/// ```
+/// let ❰ box foo ❱ = box 42;
+/// ```
+///
+/// [Unstable book](https://doc.rust-lang.org/unstable-book/language-features/box-patterns.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BoxPat {
     pub(crate) syntax: SyntaxNode,
@@ -810,7 +1545,16 @@ impl BoxPat {
     pub fn box_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![box]) }
     pub fn pat(&self) -> Option<Pat> { support::child(&self.syntax) }
 }
-
+/// Bind pattern.
+///
+/// ```
+/// match foo {
+///     Some(❰ ref mut bar ❱) => {}
+///     ❰ baz @ None ❱ => {}
+/// }
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html#identifier-patterns)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct BindPat {
     pub(crate) syntax: SyntaxNode,
@@ -823,7 +1567,13 @@ impl BindPat {
     pub fn at_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![@]) }
     pub fn pat(&self) -> Option<Pat> { support::child(&self.syntax) }
 }
-
+/// Placeholder pattern a.k.a. the wildcard pattern or the underscore.
+///
+/// ```
+/// let ❰ _ ❱ = foo;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html#wildcard-pattern)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PlaceholderPat {
     pub(crate) syntax: SyntaxNode,
@@ -831,7 +1581,16 @@ pub struct PlaceholderPat {
 impl PlaceholderPat {
     pub fn underscore_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct DotDotPat {
     pub(crate) syntax: SyntaxNode,
@@ -839,7 +1598,15 @@ pub struct DotDotPat {
 impl DotDotPat {
     pub fn dotdot_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PathPat {
     pub(crate) syntax: SyntaxNode,
@@ -847,7 +1614,13 @@ pub struct PathPat {
 impl PathPat {
     pub fn path(&self) -> Option<Path> { support::child(&self.syntax) }
 }
-
+/// Slice pattern.
+///
+/// ```
+/// let ❰ [foo, bar, baz] ❱ = [1, 2, 3];
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html#slice-patterns)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct SlicePat {
     pub(crate) syntax: SyntaxNode,
@@ -857,13 +1630,33 @@ impl SlicePat {
     pub fn args(&self) -> AstChildren<Pat> { support::children(&self.syntax) }
     pub fn r_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![']']) }
 }
-
+/// Range pattern.
+///
+/// ```
+/// match foo {
+///     ❰ 0..42 ❱ => {}
+///     ❰ 0..=42 ❱ => {}
+/// }
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html#range-patterns)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RangePat {
     pub(crate) syntax: SyntaxNode,
 }
 impl RangePat {}
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LiteralPat {
     pub(crate) syntax: SyntaxNode,
@@ -871,7 +1664,13 @@ pub struct LiteralPat {
 impl LiteralPat {
     pub fn literal(&self) -> Option<Literal> { support::child(&self.syntax) }
 }
-
+/// Macro invocation in pattern position.
+///
+/// ```
+/// let ❰ foo!(my custom syntax) ❱ = baz;
+///
+/// ```
+/// [Reference](https://doc.rust-lang.org/reference/macros.html#macro-invocation)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MacroPat {
     pub(crate) syntax: SyntaxNode,
@@ -879,7 +1678,13 @@ pub struct MacroPat {
 impl MacroPat {
     pub fn macro_call(&self) -> Option<MacroCall> { support::child(&self.syntax) }
 }
-
+/// Record literal pattern.
+///
+/// ```
+/// let ❰ foo::Bar { baz, .. } ❱ = bruh;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html#struct-patterns)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordPat {
     pub(crate) syntax: SyntaxNode,
@@ -890,7 +1695,13 @@ impl RecordPat {
     }
     pub fn path(&self) -> Option<Path> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordFieldPatList {
     pub(crate) syntax: SyntaxNode,
@@ -905,7 +1716,15 @@ impl RecordFieldPatList {
     pub fn dotdot_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![..]) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct RecordFieldPat {
     pub(crate) syntax: SyntaxNode,
@@ -916,7 +1735,13 @@ impl RecordFieldPat {
     pub fn colon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![:]) }
     pub fn pat(&self) -> Option<Pat> { support::child(&self.syntax) }
 }
-
+/// Tuple struct literal pattern.
+///
+/// ```
+/// let ❰ foo::Bar(baz, bruh) ❱ = bruuh;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/patterns.html#tuple-struct-patterns)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TupleStructPat {
     pub(crate) syntax: SyntaxNode,
@@ -927,7 +1752,14 @@ impl TupleStructPat {
     pub fn args(&self) -> AstChildren<Pat> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TuplePat {
     pub(crate) syntax: SyntaxNode,
@@ -937,7 +1769,17 @@ impl TuplePat {
     pub fn args(&self) -> AstChildren<Pat> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Visibility {
     pub(crate) syntax: SyntaxNode,
@@ -948,7 +1790,29 @@ impl Visibility {
     pub fn self_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![self]) }
     pub fn crate_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Name {
     pub(crate) syntax: SyntaxNode,
@@ -956,13 +1820,41 @@ pub struct Name {
 impl Name {
     pub fn ident_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![ident]) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct NameRef {
     pub(crate) syntax: SyntaxNode,
 }
 impl 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MacroCall {
     pub(crate) syntax: SyntaxNode,
@@ -976,7 +1868,18 @@ impl MacroCall {
     pub fn token_tree(&self) -> Option<TokenTree> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![;]) }
 }
-
+/// Attribute.
+///
+/// ```
+/// ❰ #![inner_attr] ❱
+///
+/// ❰ #[attr] ❱
+/// ❰ #[foo = "bar"] ❱
+/// ❰ #[baz(bruh::bruuh = "42")] ❱
+/// struct Foo;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/attributes.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Attr {
     pub(crate) syntax: SyntaxNode,
@@ -990,13 +1893,32 @@ impl Attr {
     pub fn input(&self) -> Option<AttrInput> { support::child(&self.syntax) }
     pub fn r_brack_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TokenTree {
     pub(crate) syntax: SyntaxNode,
 }
 impl 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeParamList {
     pub(crate) syntax: SyntaxNode,
@@ -1009,7 +1931,13 @@ impl TypeParamList {
     pub fn const_params(&self) -> AstChildren<ConstParam> { support::children(&self.syntax) }
     pub fn r_angle_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![>]) }
 }
-
+/// Single type parameter **declaration**.
+///
+/// ```
+/// fn foo<❰ K ❱, ❰ I ❱, ❰ E: Debug ❱, ❰ V = DefaultType ❱>() {}
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/items/generics.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeParam {
     pub(crate) syntax: SyntaxNode,
@@ -1021,7 +1949,12 @@ impl TypeParam {
     pub fn eq_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=]) }
     pub fn default_type(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ConstParam {
     pub(crate) syntax: SyntaxNode,
@@ -1033,7 +1966,13 @@ impl ConstParam {
     pub fn eq_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=]) }
     pub fn default_val(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LifetimeParam {
     pub(crate) syntax: SyntaxNode,
@@ -1044,7 +1983,20 @@ impl LifetimeParam {
         support::token(&self.syntax, T![lifetime])
     }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeBound {
     pub(crate) syntax: SyntaxNode,
@@ -1056,7 +2008,21 @@ impl TypeBound {
     pub fn const_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![const]) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeBoundList {
     pub(crate) syntax: SyntaxNode,
@@ -1064,7 +2030,18 @@ pub struct TypeBoundList {
 impl TypeBoundList {
     pub fn bounds(&self) -> AstChildren<TypeBound> { support::children(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct WherePred {
     pub(crate) syntax: SyntaxNode,
@@ -1076,7 +2053,14 @@ impl WherePred {
     }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// Where clause.
+///
+/// ```
+/// trait Foo<'a, T> ❰ where 'a: 'static, T: Debug ❱ {}
+///
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/items/generics.html#where-clauses)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct WhereClause {
     pub(crate) syntax: SyntaxNode,
@@ -1085,13 +2069,42 @@ impl WhereClause {
     pub fn where_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![where]) }
     pub fn predicates(&self) -> AstChildren<WherePred> { support::children(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Abi {
     pub(crate) syntax: SyntaxNode,
 }
 impl Abi {}
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ExprStmt {
     pub(crate) syntax: SyntaxNode,
@@ -1101,7 +2114,16 @@ impl ExprStmt {
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LetStmt {
     pub(crate) syntax: SyntaxNode,
@@ -1115,7 +2137,18 @@ impl LetStmt {
     pub fn initializer(&self) -> Option<Expr> { support::child(&self.syntax) }
     pub fn semicolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Condition {
     pub(crate) syntax: SyntaxNode,
@@ -1126,7 +2159,18 @@ impl Condition {
     pub fn eq_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=]) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ParamList {
     pub(crate) syntax: SyntaxNode,
@@ -1137,7 +2181,19 @@ impl ParamList {
     pub fn params(&self) -> AstChildren<Param> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct SelfParam {
     pub(crate) syntax: SyntaxNode,
@@ -1152,7 +2208,17 @@ impl SelfParam {
     }
     pub fn self_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Param {
     pub(crate) syntax: SyntaxNode,
@@ -1163,7 +2229,16 @@ impl Param {
     pub fn pat(&self) -> Option<Pat> { support::child(&self.syntax) }
     pub fn dotdotdot_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct UseItem {
     pub(crate) syntax: SyntaxNode,
@@ -1174,7 +2249,16 @@ impl UseItem {
     pub fn use_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![use]) }
     pub fn use_tree(&self) -> Option<UseTree> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct UseTree {
     pub(crate) syntax: SyntaxNode,
@@ -1185,7 +2269,16 @@ impl UseTree {
     pub fn use_tree_list(&self) -> Option<UseTreeList> { support::child(&self.syntax) }
     pub fn alias(&self) -> Option<Alias> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Alias {
     pub(crate) syntax: SyntaxNode,
@@ -1194,7 +2287,14 @@ impl ast::NameOwner for Alias {}
 impl Alias {
     pub fn as_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct UseTreeList {
     pub(crate) syntax: SyntaxNode,
@@ -1204,7 +2304,14 @@ impl UseTreeList {
     pub fn use_trees(&self) -> AstChildren<UseTree> { support::children(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ExternCrateItem {
     pub(crate) syntax: SyntaxNode,
@@ -1217,7 +2324,13 @@ impl ExternCrateItem {
     pub fn name_ref(&self) -> Option<NameRef> { support::child(&self.syntax) }
     pub fn alias(&self) -> Option<Alias> { support::child(&self.syntax) }
 }
-
+/// Call site arguments list.
+///
+/// ```
+/// foo::<T, U>❰ (42, true) ❱;
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/expressions/call-expr.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ArgList {
     pub(crate) syntax: SyntaxNode,
@@ -1227,16 +2340,41 @@ impl ArgList {
     pub fn args(&self) -> AstChildren<Expr> { support::children(&self.syntax) }
     pub fn r_paren_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Path {
     pub(crate) syntax: SyntaxNode,
 }
 impl Path {
     pub fn segment(&self) -> Option<PathSegment> { support::child(&self.syntax) }
+    pub fn coloncolon_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![::]) }
     pub fn qualifier(&self) -> Option<Path> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct PathSegment {
     pub(crate) syntax: SyntaxNode,
@@ -1254,7 +2392,15 @@ impl PathSegment {
     pub fn path_type(&self) -> Option<PathType> { support::child(&self.syntax) }
     pub fn r_angle_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeArgList {
     pub(crate) syntax: SyntaxNode,
@@ -1269,7 +2415,13 @@ impl TypeArgList {
     pub fn const_args(&self) -> AstChildren<ConstArg> { support::children(&self.syntax) }
     pub fn r_angle_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct TypeArg {
     pub(crate) syntax: SyntaxNode,
@@ -1277,7 +2429,13 @@ pub struct TypeArg {
 impl TypeArg {
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// 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 ❱> {}
+/// ```
+///
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct AssocTypeArg {
     pub(crate) syntax: SyntaxNode,
@@ -1288,7 +2446,15 @@ impl AssocTypeArg {
     pub fn eq_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=]) }
     pub fn type_ref(&self) -> Option<TypeRef> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct LifetimeArg {
     pub(crate) syntax: SyntaxNode,
@@ -1298,24 +2464,41 @@ impl LifetimeArg {
         support::token(&self.syntax, T![lifetime])
     }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ConstArg {
     pub(crate) syntax: SyntaxNode,
 }
 impl ConstArg {
     pub fn literal(&self) -> Option<Literal> { support::child(&self.syntax) }
-    pub fn eq_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T![=]) }
     pub fn block_expr(&self) -> Option<BlockExpr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MacroItems {
     pub(crate) syntax: SyntaxNode,
 }
 impl ast::ModuleItemOwner for MacroItems {}
 impl MacroItems {}
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MacroStmts {
     pub(crate) syntax: SyntaxNode,
@@ -1324,7 +2507,18 @@ impl MacroStmts {
     pub fn statements(&self) -> AstChildren<Stmt> { support::children(&self.syntax) }
     pub fn expr(&self) -> Option<Expr> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ExternItemList {
     pub(crate) syntax: SyntaxNode,
@@ -1335,7 +2529,18 @@ impl ExternItemList {
     pub fn extern_items(&self) -> AstChildren<ExternItem> { support::children(&self.syntax) }
     pub fn r_curly_token(&self) -> Option<SyntaxToken> { support::token(&self.syntax, T!['}']) }
 }
-
+/// Extern block.
+///
+/// ```
+/// ❰
+///     extern "C" {
+///         fn foo();
+///     }
+/// ❱
+///
+/// ```
+///
+/// [Reference](https://doc.rust-lang.org/reference/items/external-blocks.html)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct ExternBlock {
     pub(crate) syntax: SyntaxNode,
@@ -1344,7 +2549,15 @@ impl ExternBlock {
     pub fn abi(&self) -> Option<Abi> { support::child(&self.syntax) }
     pub fn extern_item_list(&self) -> Option<ExternItemList> { support::child(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MetaItem {
     pub(crate) syntax: SyntaxNode,
@@ -1355,7 +2568,15 @@ impl MetaItem {
     pub fn attr_input(&self) -> Option<AttrInput> { support::child(&self.syntax) }
     pub fn nested_meta_items(&self) -> AstChildren<MetaItem> { support::children(&self.syntax) }
 }
-
+/// 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)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct MacroDef {
     pub(crate) syntax: SyntaxNode,
@@ -1364,7 +2585,7 @@ impl MacroDef {
     pub fn name(&self) -> Option<Name> { support::child(&self.syntax) }
     pub fn token_tree(&self) -> Option<TokenTree> { support::child(&self.syntax) }
 }
-
+/// Any kind of nominal type definition.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum NominalDef {
     StructDef(StructDef),
@@ -1374,14 +2595,14 @@ pub enum NominalDef {
 impl ast::NameOwner for NominalDef {}
 impl ast::TypeParamsOwner for NominalDef {}
 impl ast::AttrsOwner for NominalDef {}
-
+/// Any kind of **declared** generic parameter
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum GenericParam {
     LifetimeParam(LifetimeParam),
     TypeParam(TypeParam),
     ConstParam(ConstParam),
 }
-
+/// Any kind of generic argument passed at instantiation site
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum GenericArg {
     LifetimeArg(LifetimeArg),
@@ -1389,7 +2610,7 @@ pub enum GenericArg {
     ConstArg(ConstArg),
     AssocTypeArg(AssocTypeArg),
 }
-
+/// Any kind of construct valid in type context
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum TypeRef {
     ParenType(ParenType),
@@ -1406,7 +2627,7 @@ pub enum TypeRef {
     ImplTraitType(ImplTraitType),
     DynTraitType(DynTraitType),
 }
-
+/// Any kind of top-level item that may appear in a module
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum ModuleItem {
     StructDef(StructDef),
@@ -1427,7 +2648,9 @@ pub enum ModuleItem {
 impl ast::NameOwner for ModuleItem {}
 impl ast::AttrsOwner for ModuleItem {}
 impl ast::VisibilityOwner for ModuleItem {}
-
+/// Any kind of item that may appear in an impl block
+///
+/// // FIXME: impl blocks can also contain MacroCall
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum AssocItem {
     FnDef(FnDef),
@@ -1436,7 +2659,9 @@ pub enum AssocItem {
 }
 impl ast::NameOwner for AssocItem {}
 impl ast::AttrsOwner for AssocItem {}
-
+/// Any kind of item that may appear in an extern block
+///
+/// // FIXME: extern blocks can also contain MacroCall
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum ExternItem {
     FnDef(FnDef),
@@ -1445,7 +2670,7 @@ pub enum ExternItem {
 impl ast::NameOwner for ExternItem {}
 impl ast::AttrsOwner for ExternItem {}
 impl ast::VisibilityOwner for ExternItem {}
-
+/// Any kind of expression
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Expr {
     TupleExpr(TupleExpr),
@@ -1481,7 +2706,7 @@ pub enum Expr {
     BoxExpr(BoxExpr),
 }
 impl ast::AttrsOwner for Expr {}
-
+/// Any kind of pattern
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Pat {
     OrPat(OrPat),
@@ -1500,25 +2725,28 @@ pub enum Pat {
     LiteralPat(LiteralPat),
     MacroPat(MacroPat),
 }
-
+/// Any kind of pattern that appears directly inside of the curly
+/// braces of a record pattern
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum RecordInnerPat {
     RecordFieldPat(RecordFieldPat),
     BindPat(BindPat),
 }
-
+/// Any kind of input to an attribute
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum AttrInput {
     Literal(Literal),
     TokenTree(TokenTree),
 }
-
+/// Any kind of statement
+/// Note: there are no empty statements, these are just represented as
+/// bare semicolons without a dedicated statement ast node.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Stmt {
     LetStmt(LetStmt),
     ExprStmt(ExprStmt),
 }
-
+/// Any kind of fields list (record or tuple field lists)
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum FieldDefList {
     RecordFieldDefList(RecordFieldDefList),