4 files changed, 15 insertions, 4 deletions

diff --git a/crates/syntax/src/algo.rs b/crates/syntax/src/algo.rs
index 241713c48..8d7a77b50 100644
--- a/crates/syntax/src/algo.rs
+++ b/crates/syntax/src/algo.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! Collection of assorted algorithms for syntax trees.
 
 use std::{hash::BuildHasherDefault, ops::RangeInclusive};
 
diff --git a/crates/syntax/src/fuzz.rs b/crates/syntax/src/fuzz.rs
index aa84239d2..256999fe0 100644
--- a/crates/syntax/src/fuzz.rs
+++ b/crates/syntax/src/fuzz.rs
@@ -1,4 +1,6 @@
-//! FIXME: write short doc here
+//! Some infrastructure for fuzzy testing.
+//!
+//! We don't normally run fuzzying, so this is hopelessly bitrotten :(
 
 use std::{
     convert::TryInto,
diff --git a/crates/syntax/src/parsing/text_tree_sink.rs b/crates/syntax/src/parsing/text_tree_sink.rs
index d63ec080b..25bfd41a1 100644
--- a/crates/syntax/src/parsing/text_tree_sink.rs
+++ b/crates/syntax/src/parsing/text_tree_sink.rs
@@ -1,4 +1,4 @@
-//! FIXME: write short doc here
+//! See [`TextTreeSink`].
 
 use std::mem;
 
diff --git a/crates/syntax/src/ptr.rs b/crates/syntax/src/ptr.rs
index d3fb7a5d9..195d2251b 100644
--- a/crates/syntax/src/ptr.rs
+++ b/crates/syntax/src/ptr.rs
@@ -1,4 +1,13 @@
-//! FIXME: write short doc here
+//! In rust-analyzer, syntax trees are transient objects.
+//!
+//! That means that we create trees when we need them, and tear them down to
+//! save memory. In this architecture, hanging on to a particular syntax node
+//! for a long time is ill-advisable, as that keeps the whole tree resident.
+//!
+//! Instead, we provide a [`SyntaxNodePtr`] type, which stores information about
+//! *location* of a particular syntax node in a tree. Its a small type which can
+//! be cheaply stored, and which can be resolved to a real [`SyntaxNode`] when
+//! necessary.
 
 use std::{
     hash::{Hash, Hasher},