diff --git a/crates/ra_hir_ty/src/lib.rs b/crates/ra_hir_ty/src/lib.rs
index 25bfc1d154..28859ba636 100644
--- a/crates/ra_hir_ty/src/lib.rs
+++ b/crates/ra_hir_ty/src/lib.rs
@@ -1,3 +1,4 @@
-//! FIXME: write short doc here
+//! Work in Progress: everything related to types, type inference and trait
+//! solving.
 
 pub mod primitive;
diff --git a/crates/ra_hir_ty/src/primitive.rs b/crates/ra_hir_ty/src/primitive.rs
index afa22448da..02a8179d94 100644
--- a/crates/ra_hir_ty/src/primitive.rs
+++ b/crates/ra_hir_ty/src/primitive.rs
@@ -1,4 +1,7 @@
-//! FIXME: write short doc here
+//! Defines primitive types, which have a couple of peculiarities:
+//!
+//! * during type inference, they can be uncertain (ie, `let x = 92;`)
+//! * they don't belong to any particular crate.
 
 use std::fmt;