diff --git a/src/collector/mod.rs b/src/collector/mod.rs
index 27435592d..44193399d 100644
--- a/src/collector/mod.rs
+++ b/src/collector/mod.rs
@@ -1,3 +1,6 @@
+/*!
+Collector module
+*/
 use SegmentReader;
 use SegmentLocalId;
 use DocId;
diff --git a/src/fastfield/mod.rs b/src/fastfield/mod.rs
index 8b47d3a0e..37b398b9a 100644
--- a/src/fastfield/mod.rs
+++ b/src/fastfield/mod.rs
@@ -1,5 +1,5 @@
 /*!
-Fast fields is a column oriented storage storage.
+Fast fields is a column oriented storage.
 
 It is the equivalent of `Lucene`'s `DocValues`.
 
diff --git a/src/lib.rs b/src/lib.rs
index d719badfb..775267892 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -103,24 +103,12 @@ mod analyzer;
 mod datastruct;
 
 pub mod termdict;
-
-/// Row-oriented, slow, compressed storage of documents
 pub mod store;
-
-/// Query module
 pub mod query;
-
 pub mod directory;
-
-/// Collector module
 pub mod collector;
-
-/// Postings module (also called inverted index)
 pub mod postings;
-
-/// Schema
 pub mod schema;
-
 pub mod fastfield;
 
 
@@ -156,15 +144,19 @@ pub mod merge_policy {
     pub use indexer::DefaultMergePolicy;
 }
 
-/// u32 identifying a document within a segment.
-/// Documents have their doc id assigned incrementally,
+/// A `u32` identifying a document within a segment.
+/// Documents have their `DocId` assigned incrementally,
 /// as they are added in the segment.
 pub type DocId = u32;
 
-/// f32 the score of a document.
+/// A f32 that represents the relevance of the document to the query
+///
+/// This is modelled internally as a `f32`. The
+/// larger the number, the more relevant the document
+/// to the search
 pub type Score = f32;
 
-/// A segment local id identifies a segment.
+/// A `SegmentLocalId` identifies a segment.
 /// It only makes sense for a given searcher.
 pub type SegmentLocalId = u32;
 
diff --git a/src/postings/mod.rs b/src/postings/mod.rs
index ed8a6998f..3cb20eb82 100644
--- a/src/postings/mod.rs
+++ b/src/postings/mod.rs
@@ -1,3 +1,7 @@
+/*!
+Postings module (also called inverted index)
+*/
+
 /// Postings module
 ///
 /// Postings, also called inverted lists, is the key datastructure
diff --git a/src/query/mod.rs b/src/query/mod.rs
index 94cce7304..044a68b77 100644
--- a/src/query/mod.rs
+++ b/src/query/mod.rs
@@ -1,7 +1,8 @@
-/// Query module
-///
-/// The query module regroups all of tantivy's query objects
-///
+/*!
+Query module
+
+The query module regroups all of tantivy's query objects
+*/
 
 mod query;
 mod boolean_query;
diff --git a/src/query/occur_filter.rs b/src/query/occur_filter.rs
index 1b21dea6e..ca80e0c1f 100644
--- a/src/query/occur_filter.rs
+++ b/src/query/occur_filter.rs
@@ -2,7 +2,7 @@ use query::Occur;
 
 
 /// An `OccurFilter` represents a filter over a bitset of
-// at most 64 elements.
+/// at most 64 elements.
 ///
 /// It wraps some simple bitmask to compute the filter
 /// rapidly.
diff --git a/src/query/phrase_query/phrase_query.rs b/src/query/phrase_query/phrase_query.rs
index b523c6e5d..3c9e4b597 100644
--- a/src/query/phrase_query/phrase_query.rs
+++ b/src/query/phrase_query/phrase_query.rs
@@ -7,7 +7,8 @@ use query::Weight;
 use Result;
 
 
-/// `PhraseQuery` matches a specific sequence of word.
+/// `PhraseQuery` matches a specific sequence of words.
+///
 /// For instance the phrase query for `"part time"` will match
 /// the sentence
 ///
diff --git a/src/query/query.rs b/src/query/query.rs
index f091442a8..a0c1f409d 100644
--- a/src/query/query.rs
+++ b/src/query/query.rs
@@ -8,7 +8,10 @@ use std::fmt;
 use std::any::Any;
 
 
-/// Query trait are in charge of defining :
+/// The `Query` trait defines a set of documents and a scoring method
+/// for those documents.
+///
+/// The `Query` trait is in charge of defining :
 ///
 /// - a set of documents
 /// - a way to score these documents
@@ -68,7 +71,10 @@ pub trait Query: fmt::Debug {
                 let mut segment_search_timer = search_timer.open("segment_search");
                 {
                     let _ = segment_search_timer.open("set_segment");
-                    try!(collector.set_segment(segment_ord as SegmentLocalId, segment_reader));
+                    try!(collector.set_segment(
+                        segment_ord as SegmentLocalId,
+                        segment_reader,
+                    ));
                 }
                 let mut scorer = try!(weight.scorer(segment_reader));
                 {
diff --git a/src/schema/mod.rs b/src/schema/mod.rs
index a9da6e7e7..be9e7cac2 100644
--- a/src/schema/mod.rs
+++ b/src/schema/mod.rs
@@ -1,7 +1,7 @@
 /*!
 
 
-# Schema definition
+# Setting your schema in Tantivy
 
 Tantivy has a very strict schema.
 The schema defines information about the fields your index contains, that is, for each field: