diff --git a/crates/ra_syntax/src/ast.rs b/crates/ra_syntax/src/ast.rs
index dcc71eabed7..9f5c41b0cd2 100644
--- a/crates/ra_syntax/src/ast.rs
+++ b/crates/ra_syntax/src/ast.rs
@@ -1,4 +1,5 @@
 //! Abstract Syntax Tree, layered on top of untyped `SyntaxNode`s
+
 mod generated;
 mod traits;
 mod tokens;
@@ -44,6 +45,7 @@ pub trait AstToken<'a> {
     }
 }
 
+/// An iterator over `SyntaxNode` children of a particular AST type.
 #[derive(Debug)]
 pub struct AstChildren<'a, N> {
     inner: SyntaxNodeChildren<'a>,
diff --git a/crates/ra_syntax/src/ast/expr_extensions.rs b/crates/ra_syntax/src/ast/expr_extensions.rs
index b24f86cecf4..1d83138102f 100644
--- a/crates/ra_syntax/src/ast/expr_extensions.rs
+++ b/crates/ra_syntax/src/ast/expr_extensions.rs
@@ -1,3 +1,5 @@
+//! Various extension methods to ast Expr Nodes, which are hard to code-generate.
+
 use crate::{
     SyntaxToken, SyntaxElement, SmolStr,
     ast::{self, AstNode, AstChildren, children, child_opt},
diff --git a/crates/ra_syntax/src/ast/extensions.rs b/crates/ra_syntax/src/ast/extensions.rs
index 342581faf7d..aec57c3807a 100644
--- a/crates/ra_syntax/src/ast/extensions.rs
+++ b/crates/ra_syntax/src/ast/extensions.rs
@@ -1,3 +1,6 @@
+//! Various extension methods to ast Nodes, which are hard to code-generate.
+//! Extensions for various expressions live in a sibling `expr_extensions` module.
+
 use itertools::Itertools;
 
 use crate::{
diff --git a/crates/ra_syntax/src/ast/tokens.rs b/crates/ra_syntax/src/ast/tokens.rs
index 7c30ff15cb9..da7d507bfda 100644
--- a/crates/ra_syntax/src/ast/tokens.rs
+++ b/crates/ra_syntax/src/ast/tokens.rs
@@ -1,3 +1,5 @@
+//! There are many AstNodes, but only a few tokens, so we hand-write them here.
+
 use crate::{
     SyntaxToken,
     SyntaxKind::{COMMENT, WHITESPACE},
diff --git a/crates/ra_syntax/src/ast/traits.rs b/crates/ra_syntax/src/ast/traits.rs
index 98aa22085ab..aaf07d731ff 100644
--- a/crates/ra_syntax/src/ast/traits.rs
+++ b/crates/ra_syntax/src/ast/traits.rs
@@ -1,3 +1,7 @@
+//! Various traits that are implemented by ast nodes.
+//!
+//! The implementations are usually trivial, and live in generated.rs
+
 use itertools::Itertools;
 
 use crate::{