Add documentation

milli/src/search/new/logger/mod.rs

@@ -7,7 +7,82 @@ use super::ranking_rule_graph::{EmptyPathsCache, ProximityGraph, RankingRuleGrap
 use super::small_bitmap::SmallBitmap;
 use super::{RankingRule, RankingRuleQueryTrait};
 
+/// Trait for structure logging the execution of a search query.
+pub trait SearchLogger<Q: RankingRuleQueryTrait> {
+    /// Logs the initial query
+    fn initial_query(&mut self, query: &Q);
+
+    /// Logs the query that was used to compute the set of all candidates
+    fn query_for_universe(&mut self, query: &Q);
+
+    /// Logs the value of the initial set of all candidates
+    fn initial_universe(&mut self, universe: &RoaringBitmap);
+
+    /// Logs the ranking rules used to perform the search query
+    fn ranking_rules(&mut self, rr: &[&mut dyn RankingRule<Q>]);
+
+    /// Logs the start of a ranking rule's iteration.
+    fn start_iteration_ranking_rule<'transaction>(
+        &mut self,
+        ranking_rule_idx: usize,
+        ranking_rule: &dyn RankingRule<'transaction, Q>,
+        query: &Q,
+        universe: &RoaringBitmap,
+    );
+    /// Logs the end of the computation of a ranking rule bucket
+    fn next_bucket_ranking_rule<'transaction>(
+        &mut self,
+        ranking_rule_idx: usize,
+        ranking_rule: &dyn RankingRule<'transaction, Q>,
+        universe: &RoaringBitmap,
+        candidates: &RoaringBitmap,
+    );
+    /// Logs the skipping of a ranking rule bucket
+    fn skip_bucket_ranking_rule<'transaction>(
+        &mut self,
+        ranking_rule_idx: usize,
+        ranking_rule: &dyn RankingRule<'transaction, Q>,
+        candidates: &RoaringBitmap,
+    );
+    /// Logs the end of a ranking rule's iteration.
+    fn end_iteration_ranking_rule<'transaction>(
+        &mut self,
+        ranking_rule_idx: usize,
+        ranking_rule: &dyn RankingRule<'transaction, Q>,
+        universe: &RoaringBitmap,
+    );
+    /// Logs the addition of document ids to the final results
+    fn add_to_results(&mut self, docids: &[u32]);
+
+    /// Logs the internal state of the words ranking rule
+    fn log_words_state(&mut self, query_graph: &Q);
+
+    /// Logs the internal state of the proximity ranking rule
+    fn log_proximity_state(
+        &mut self,
+        query_graph: &RankingRuleGraph<ProximityGraph>,
+        paths: &[Vec<u16>],
+        empty_paths_cache: &EmptyPathsCache,
+        universe: &RoaringBitmap,
+        distances: Vec<Vec<(u16, SmallBitmap)>>,
+        cost: u16,
+    );
+
+    /// Logs the internal state of the typo ranking rule
+    fn log_typo_state(
+        &mut self,
+        query_graph: &RankingRuleGraph<TypoGraph>,
+        paths: &[Vec<u16>],
+        empty_paths_cache: &EmptyPathsCache,
+        universe: &RoaringBitmap,
+        distances: Vec<Vec<(u16, SmallBitmap)>>,
+        cost: u16,
+    );
+}
+
+/// A dummy [`SearchLogger`] which does nothing.
 pub struct DefaultSearchLogger;
+
 impl<Q: RankingRuleQueryTrait> SearchLogger<Q> for DefaultSearchLogger {
     fn initial_query(&mut self, _query: &Q) {}
 
@@ -76,63 +151,3 @@ impl<Q: RankingRuleQueryTrait> SearchLogger<Q> for DefaultSearchLogger {
     ) {
     }
 }
-
-pub trait SearchLogger<Q: RankingRuleQueryTrait> {
-    fn initial_query(&mut self, query: &Q);
-
-    fn query_for_universe(&mut self, query: &Q);
-
-    fn initial_universe(&mut self, universe: &RoaringBitmap);
-
-    fn ranking_rules(&mut self, rr: &[&mut dyn RankingRule<Q>]);
-
-    fn start_iteration_ranking_rule<'transaction>(
-        &mut self,
-        ranking_rule_idx: usize,
-        ranking_rule: &dyn RankingRule<'transaction, Q>,
-        query: &Q,
-        universe: &RoaringBitmap,
-    );
-    fn next_bucket_ranking_rule<'transaction>(
-        &mut self,
-        ranking_rule_idx: usize,
-        ranking_rule: &dyn RankingRule<'transaction, Q>,
-        universe: &RoaringBitmap,
-        candidates: &RoaringBitmap,
-    );
-    fn skip_bucket_ranking_rule<'transaction>(
-        &mut self,
-        ranking_rule_idx: usize,
-        ranking_rule: &dyn RankingRule<'transaction, Q>,
-        candidates: &RoaringBitmap,
-    );
-    fn end_iteration_ranking_rule<'transaction>(
-        &mut self,
-        ranking_rule_idx: usize,
-        ranking_rule: &dyn RankingRule<'transaction, Q>,
-        universe: &RoaringBitmap,
-    );
-    fn add_to_results(&mut self, docids: &[u32]);
-
-    fn log_words_state(&mut self, query_graph: &Q);
-
-    fn log_proximity_state(
-        &mut self,
-        query_graph: &RankingRuleGraph<ProximityGraph>,
-        paths: &[Vec<u16>],
-        empty_paths_cache: &EmptyPathsCache,
-        universe: &RoaringBitmap,
-        distances: Vec<Vec<(u16, SmallBitmap)>>,
-        cost: u16,
-    );
-
-    fn log_typo_state(
-        &mut self,
-        query_graph: &RankingRuleGraph<TypoGraph>,
-        paths: &[Vec<u16>],
-        empty_paths_cache: &EmptyPathsCache,
-        universe: &RoaringBitmap,
-        distances: Vec<Vec<(u16, SmallBitmap)>>,
-        cost: u16,
-    );
-}