Added comments

src/postings/docset.rs

@@ -104,6 +104,17 @@ pub trait DocSet {
             bitset.insert(self.doc());
         }
     }
+
+    /// Returns the number documents matching.
+    ///
+    /// Calling this method consumes the `DocSet`.
+    fn count(&mut self) -> u32 {
+        let mut count = 0u32;
+        while self.advance() {
+            count += 1u32;
+        }
+        count
+    }
 }
 
 impl<TDocSet: DocSet + ?Sized> DocSet for Box<TDocSet> {

src/query/query.rs

@@ -53,7 +53,7 @@ pub trait Query: fmt::Debug {
     /// See [`Weight`](./trait.Weight.html).
     fn weight(&self, searcher: &Searcher, scoring_enabled: bool) -> Result<Box<Weight>>;
 
-
+    /// Returns the number of documents matching the query.
     fn count(&self, searcher: &Searcher) -> Result<usize> {
         let weight = self.weight(searcher, false)?;
         let mut result = 0;

src/query/score_combiner.rs

@@ -5,8 +5,16 @@ use query::Scorer;
 /// The `ScoreCombiner` trait defines how to compute
 /// an overall score given a list of scores.
 pub trait ScoreCombiner: Default + Clone + Copy {
+    /// Aggregates the score combiner with the given scorer.
+    ///
+    /// The `ScoreCombiner` may decide to call `.scorer.score()`
+    /// or not.
     fn update<TScorer: Scorer>(&mut self, scorer: &mut TScorer);
+
+    /// Clears the score combiner state back to its initial state.
     fn clear(&mut self);
+
+    /// Returns the aggregate score.
     fn score(&self) -> Score;
 }
 

src/query/scorer.rs

@@ -22,14 +22,6 @@ pub trait Scorer: DocSet {
             collector.collect(self.doc(), self.score());
         }
     }
-
-    fn count(&mut self) -> u32 {
-        let mut count = 0u32;
-        while self.advance() {
-            count += 1u32;
-        }
-        count
-    }
 }
 
 impl<'a> Scorer for Box<Scorer + 'a> {
@@ -41,11 +33,6 @@ impl<'a> Scorer for Box<Scorer + 'a> {
         let scorer = self.deref_mut();
         scorer.collect(collector);
     }
-
-    fn count(&mut self) -> u32 {
-        let scorer = self.deref_mut();
-        scorer.count()
-    }
 }
 
 /// `EmptyScorer` is a dummy `Scorer` in which no document matches.

src/query/weight.rs

@@ -11,6 +11,7 @@ pub trait Weight {
     /// See [`Query`](./trait.Query.html).
     fn scorer<'a>(&'a self, reader: &'a SegmentReader) -> Result<Box<Scorer + 'a>>;
 
+    /// Returns the number documents within the given `SegmentReader`.
     fn count(&self, reader: &SegmentReader) -> Result<u32> {
         Ok(self.scorer(reader)?.count())
     }