From 6f55e7844ce7a72f2b4ee7e64be9d1e98cec7700 Mon Sep 17 00:00:00 2001
From: ManyTheFish <many@meilisearch.com>
Date: Mon, 17 Oct 2022 14:41:57 +0200
Subject: [PATCH] Add some code comments

---
 milli/src/search/criteria/initial.rs | 9 +++++++--
 milli/src/search/mod.rs              | 2 ++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/milli/src/search/criteria/initial.rs b/milli/src/search/criteria/initial.rs
index 9a9565182..14d368d4e 100644
--- a/milli/src/search/criteria/initial.rs
+++ b/milli/src/search/criteria/initial.rs
@@ -5,7 +5,9 @@ use crate::search::criteria::{resolve_query_tree, Context};
 use crate::search::query_tree::Operation;
 use crate::search::Distinct;
 use crate::Result;
-
+/// Initial is a mandatory criterion, it is always the first
+/// and is meant to initalize the CriterionResult used by the other criteria.
+/// It behave like an [Once Iterator](https://doc.rust-lang.org/std/iter/struct.Once.html) and will return Some(CriterionResult) only one time.
 pub struct Initial<'t, D> {
     ctx: &'t dyn Context<'t>,
     answer: Option<CriterionResult>,
@@ -38,18 +40,21 @@ impl<D: Distinct> Criterion for Initial<'_, D> {
             .take()
             .map(|mut answer| {
                 if self.exhaustive_number_hits && answer.query_tree.is_some() {
+                    // resolve the whole query tree to retrieve an exhastive list of documents matching the query.
                     let mut candidates = resolve_query_tree(
                         self.ctx,
                         answer.query_tree.as_ref().unwrap(),
                         &mut params.wdcache,
                     )?;
 
+                    // Apply the filters on the documents retrieved with the query tree.
                     if let Some(ref filtered_candidates) = answer.filtered_candidates {
                         candidates &= filtered_candidates;
                     }
 
+                    // because the bucket_candidates should be an exhastive count of the matching documents,
+                    // we precompute the distinct attributes.
                     let bucket_candidates = match &mut self.distinct {
-                        // may be really time consuming
                         Some(distinct) => {
                             let mut bucket_candidates = RoaringBitmap::new();
                             for c in distinct.distinct(candidates.clone(), RoaringBitmap::new()) {
diff --git a/milli/src/search/mod.rs b/milli/src/search/mod.rs
index 270beb52a..20003c676 100644
--- a/milli/src/search/mod.rs
+++ b/milli/src/search/mod.rs
@@ -109,6 +109,8 @@ impl<'a> Search<'a> {
         self
     }
 
+    /// Force the search to exhastivelly compute the number of candidates,
+    /// this will increase the search time but allows finite pagination.
     pub fn exhaustive_number_hits(&mut self, exhaustive_number_hits: bool) -> &mut Search<'a> {
         self.exhaustive_number_hits = exhaustive_number_hits;
         self