issue/50 Added documentation for the query object.

1 files changed, 44 insertions, 6 deletions

diff --git a/src/query/query.rs b/src/query/query.rs
index 0e27c13..3b15f30 100644
--- a/src/query/query.rs
+++ b/src/query/query.rs
@@ -8,17 +8,55 @@ use std::fmt;
 use std::any::Any;
 
 
-/// Queries represent the query of the user, and are in charge
-/// of the logic defining the set of documents that should be
-/// sent to the collector, as well as the way to score the
-/// documents. 
+/// Query trait are in charge of defining :
+/// 
+/// - a set of documents
+/// - a way to score these documents
+///
+/// When performing a [search](#method.search),  these documents will then
+/// be pushed to a [Collector](../collector/trait.Collector.html),
+/// which will in turn be in charge of deciding what to do with them.   
+///  
+/// Concretely, this scored docset is represented by the
+/// [`Scorer`](./trait.Scorer.html) trait.
+///
+/// Because our index is actually split into segments, the 
+/// query does not actually directly creates `DocSet` object.
+/// Instead, the query creates a [`Weight`](./trait.Weight.html)
+/// object for a given searcher. 
+///  
+/// The weight object, in turn, makes it possible to create 
+/// a scorer for a specific [`SegmentReader`](../struct.SegmentReader.html).
+/// 
+/// So to sum it up :
+/// - a `Query` is recipe to define a set of documents as well the way to score them.
+/// - a `Weight` is this recipe tied to a specific `Searcher`. It may for instance 
+/// hold statistics about the different term of the query. It is created by the query.
+/// - a `Scorer` is a cursor over the set of matching documents, for a specific 
+/// [`SegmentReader`](../struct.SegmentReader.html). It is created by the [`Weight`](./trait.Weight.html).
+///
+/// When implementing a new type of `Query`, it is normal to implement a
+/// dedicated `Query`, `Weight` and `Scorer`.
 pub trait Query: fmt::Debug {
     
+    /// Used to make it possible to cast Box<Query>
+    /// into a specific type. This is mostly useful for unit tests.
     fn as_any(&self) -> &Any;
 
+    /// Create the weight associated to a query.
+    ///
+    /// See [Weight](./trait.Weight.html).
     fn weight(&self, searcher: &Searcher) -> Result<Box<Weight>>;
-        
-    /// Perform the search operation
+    
+    /// Search works as follows :
+    ///
+    /// First the weight object associated to the query is created.
+    ///  
+    /// Then, the query loops over the segments and for each segment :
+    /// - setup the collector and informs it that the segment being processed has changed.
+    /// - creates a `Scorer` object associated for this segment
+    /// - iterate throw the matched documents and push them to the collector.
+    ///
     fn search(
         &self,
         searcher: &Searcher,