From c3d6e1bd3f5c793dc5df6b668a07ccc4d81455a9 Mon Sep 17 00:00:00 2001
From: Daniel <kingdread@gmx.de>
Date: Fri, 12 Jun 2020 01:03:14 +0200
Subject: more documentation for filters::values

---
 src/filters/values.rs | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/filters/values.rs b/src/filters/values.rs
index 543b59c..f64d6dd 100644
--- a/src/filters/values.rs
+++ b/src/filters/values.rs
@@ -1,3 +1,16 @@
+//! Value extractor system for raidgrep filters.
+//!
+//! [`Comparators`][Comparator] are special filters that work by first producing a value from a
+//! given log (via the [`Producer`][Producer]) trait and then applying a comparison operator
+//! ([`CompOp`][CompOp]) between the results. This type of filter gives a lot of flexibility, as it
+//! can reduce the number of hard-coded filters one has to create (for example, `-before` and
+//! `-after` can be merged).
+//!
+//! A [`Comparator`][Comparator] can only compare producers which produce the same type of value,
+//! and that value must define a total order (i.e. it must implement [`Ord`][Ord]). Note that the
+//! actual comparison is done on filter time, that is a [`Comparator`][Comparator] is basically a
+//! filter that first uses the producers to produce a value from the given log, and then compares
+//! the two resulting values with the given comparison operator.
 use std::{
     cmp::Ordering,
     fmt::{self, Debug},
@@ -8,22 +21,41 @@ use chrono::{DateTime, Duration, Utc};
 use super::{log::LogFilter, Filter};
 use crate::{EarlyLogResult, LogResult};
 
+/// A producer for a given value.
+///
+/// A producer is something that produces a value of a certain type from a log, which can then be
+/// used by [`Comparators`][Comparator] to do the actual comparison.
 pub trait Producer: Send + Sync + Debug {
+    /// Type of the value that will be produced.
     type Output;
 
+    /// Early production.
+    ///
+    /// This function should be implemented if the value can already be produced without the
+    /// complete log being parsed. This can speed up filtering if a lot of logs end up being thrown
+    /// away.
+    ///
+    /// If a value cannot be produced early, `None` should be returned.
     fn produce_early(&self, _early_log: &EarlyLogResult) -> Option<Self::Output> {
         None
     }
 
+    /// Produce the value from the given log.
     fn produce(&self, log: &LogResult) -> Self::Output;
 }
 
+/// The comparison operator to be used.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
 pub enum CompOp {
+    /// The first value must be strictly less than the second value.
     Less,
+    /// The first value must be less or equal to the second value.
     LessEqual,
+    /// Both values must be equal.
     Equal,
+    /// The first value must be greater or equal to the second value.
     GreaterEqual,
+    /// The first value must be strictly greater than the second value.
     Greater,
 }
 
@@ -41,6 +73,7 @@ impl fmt::Display for CompOp {
 }
 
 impl CompOp {
+    /// Check whether the comparison operator matches the given ordering.
     pub fn matches(self, cmp: Ordering) -> bool {
         match cmp {
             Ordering::Less => self == CompOp::Less || self == CompOp::LessEqual,
@@ -75,6 +108,12 @@ where
     }
 }
 
+/// Create a log filter that works by comparing two values.
+///
+/// The values will be produced by the given producers.
+///
+/// This function acts as a "bridge" between the value producers and the log filter system by
+/// actually evaluating the comparison.
 pub fn comparison<V: 'static>(
     lhs: Box<dyn Producer<Output = V>>,
     op: CompOp,
@@ -100,6 +139,7 @@ impl<V: Send + Sync + Debug + Clone> Producer for ConstantProducer<V> {
     }
 }
 
+/// A producer that always produces the given constant, regardless of the log.
 pub fn constant<V: Send + Sync + Debug + Clone + 'static>(
     value: V,
 ) -> Box<dyn Producer<Output = V>> {
@@ -124,6 +164,7 @@ impl Producer for TimeProducer {
     }
 }
 
+/// A producer that produces the time at which a log was created.
 pub fn time() -> Box<dyn Producer<Output = DateTime<Utc>>> {
     Box::new(TimeProducer)
 }
@@ -139,6 +180,7 @@ impl Producer for DurationProducer {
     }
 }
 
+/// A producer that produces the duration that a fight lasted in the log.
 pub fn duration() -> Box<dyn Producer<Output = Duration>> {
     Box::new(DurationProducer)
 }
-- 
cgit v1.2.3