diff --git a/crates/ra_syntax/src/ast/generated.rs b/crates/ra_syntax/src/ast/generated.rs
index d473478a910..420d9090c2f 100644
--- a/crates/ra_syntax/src/ast/generated.rs
+++ b/crates/ra_syntax/src/ast/generated.rs
@@ -1,6 +1,12 @@
 // This file is automatically generated based on the file `./generated.rs.tera` when `cargo gen-syntax` is run
 // Do not edit manually
 
+//! This module contains auto-generated Rust AST. Like `SyntaxNode`s, AST nodes
+//! are generic over ownership: `X<'a>` things are `Copy` references, `XNode`
+//! are Arc-based. You can switch between the two variants using `.owned` and
+//! `.borrowed` functions. Most of the code works with borowed mode, and only
+//! this mode has all AST accessors.
+
 #![cfg_attr(rustfmt, rustfmt_skip)]
 
 use crate::{
diff --git a/crates/ra_syntax/src/ast/generated.rs.tera b/crates/ra_syntax/src/ast/generated.rs.tera
index 6e28575b2dd..d4fc6b5bd85 100644
--- a/crates/ra_syntax/src/ast/generated.rs.tera
+++ b/crates/ra_syntax/src/ast/generated.rs.tera
@@ -3,6 +3,12 @@ the below applies to the result of this template
 #}// This file is automatically generated based on the file `./generated.rs.tera` when `cargo gen-syntax` is run
 // Do not edit manually
 
+//! This module contains auto-generated Rust AST. Like `SyntaxNode`s, AST nodes
+//! are generic over ownership: `X<'a>` things are `Copy` references, `XNode`
+//! are Arc-based. You can switch between the two variants using `.owned` and
+//! `.borrowed` functions. Most of the code works with borowed mode, and only
+//! this mode has all AST accessors.
+
 #![cfg_attr(rustfmt, rustfmt_skip)]
 
 use crate::{
diff --git a/crates/ra_syntax/src/ast/mod.rs b/crates/ra_syntax/src/ast/mod.rs
index 4355531d002..d93f926729d 100644
--- a/crates/ra_syntax/src/ast/mod.rs
+++ b/crates/ra_syntax/src/ast/mod.rs
@@ -12,6 +12,10 @@ use crate::{
     SyntaxNodeRef,
 };
 
+/// The main trait to go from untyped `SyntaxNode`  to a typed ast. The
+/// conversion itself has zero runtime cost: ast and syntax nodes have exactly
+/// the same representation: a pointer to the tree root and a pointer to the
+/// node itself.
 pub trait AstNode<'a>: Clone + Copy + 'a {
     fn cast(syntax: SyntaxNodeRef<'a>) -> Option<Self>
     where