From cd51ed0f9ffa8a5e117d6dc71b8a9491bad323c3 Mon Sep 17 00:00:00 2001
From: Paul Masurel <paul.masurel@gmail.com>
Date: Sat, 17 Feb 2018 16:59:28 +0900
Subject: [PATCH] Added comments

---
 src/postings/docset.rs      | 11 +++++++++++
 src/query/query.rs          |  2 +-
 src/query/score_combiner.rs |  8 ++++++++
 src/query/scorer.rs         | 13 -------------
 src/query/weight.rs         |  1 +
 5 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/src/postings/docset.rs b/src/postings/docset.rs
index 8d5c36efb..8b6353779 100644
--- a/src/postings/docset.rs
+++ b/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> {
diff --git a/src/query/query.rs b/src/query/query.rs
index e01e60409..7f127a5ee 100644
--- a/src/query/query.rs
+++ b/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;
diff --git a/src/query/score_combiner.rs b/src/query/score_combiner.rs
index eb218e97d..50bc85b9f 100644
--- a/src/query/score_combiner.rs
+++ b/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;
 }
 
diff --git a/src/query/scorer.rs b/src/query/scorer.rs
index 58574e405..b76b6187d 100644
--- a/src/query/scorer.rs
+++ b/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.
diff --git a/src/query/weight.rs b/src/query/weight.rs
index 0d81af56e..5e73f7311 100644
--- a/src/query/weight.rs
+++ b/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())
     }