Improve docs for leapjoin and leapers

src/treefrog.rs

@@ -106,7 +106,7 @@ tuple_leapers!(A B C D E);
 tuple_leapers!(A B C D E F);
 tuple_leapers!(A B C D E F G);
 
-/// Methods to support treefrog leapjoin.
+/// Methods to support [treefrog leapjoin](crate::Variable::from_leapjoin).
 pub trait Leaper<'leap, Tuple, Val> {
     /// Estimates the number of proposed values.
     fn count(&mut self, prefix: &Tuple) -> usize;
@@ -121,11 +121,12 @@ pub(crate) mod filters {
     use super::Leapers;
 
     /// A treefrog leaper that tests each of the tuples from the main
-    /// input (the "prefix"). Use like `PrefixFilter::from(|tuple|
-    /// ...)`; if the closure returns true, then the tuple is
-    /// retained, else it will be ignored. This leaper can be used in
-    /// isolation in which case it just acts like a filter on the
-    /// input (the "proposed value" will be `()` type).
+    /// input (the "prefix") against a predicate.
+    ///
+    /// Use like `PrefixFilter::from(|tuple| ...)`; if the closure returns
+    /// true, then the tuple is retained, else it will be ignored. This
+    /// leaper can be used in isolation in which case it just acts like
+    /// a filter on the input (the "proposed value" will be `()` type).
     pub struct PrefixFilter<Tuple, Func: Fn(&Tuple) -> bool> {
         phantom: ::std::marker::PhantomData<Tuple>,
         predicate: Func,
@@ -238,6 +239,7 @@ pub(crate) mod filters {
     }
 
     /// A treefrog leaper based on a predicate of prefix and value.
+    ///
     /// Use like `ValueFilter::from(|tuple, value| ...)`. The closure
     /// should return true if `value` ought to be retained. The
     /// `value` will be a value proposed elsewhere by an `extend_with`
@@ -285,6 +287,8 @@ pub(crate) mod filters {
 /// Extension method for relations.
 pub trait RelationLeaper<Key: Ord, Val: Ord> {
     /// Extend with `Val` using the elements of the relation.
+    ///
+    /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, the key is looked up in this relation, then all corresponding values are added to the source.
     fn extend_with<'leap, Tuple: Ord, Func: Fn(&Tuple) -> Key>(
         &'leap self,
         key_func: Func,
@@ -293,6 +297,8 @@ pub trait RelationLeaper<Key: Ord, Val: Ord> {
         Key: 'leap,
         Val: 'leap;
     /// Extend with `Val` using the complement of the relation.
+    ///
+    /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, the key is looked up in this relation, then all corresponding values are removed from the source.
     fn extend_anti<'leap, Tuple: Ord, Func: Fn(&Tuple) -> Key>(
         &'leap self,
         key_func: Func,
@@ -301,6 +307,8 @@ pub trait RelationLeaper<Key: Ord, Val: Ord> {
         Key: 'leap,
         Val: 'leap;
     /// Extend with any value if tuple is present in relation.
+    ///
+    /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, then only keys found in the relation are kept in the source.
     fn filter_with<'leap, Tuple: Ord, Func: Fn(&Tuple) -> (Key, Val)>(
         &'leap self,
         key_func: Func,
@@ -309,6 +317,8 @@ pub trait RelationLeaper<Key: Ord, Val: Ord> {
         Key: 'leap,
         Val: 'leap;
     /// Extend with any value if tuple is absent from relation.
+    ///
+    /// When used in a [leapjoin](`crate::Variable::from_leapjoin`), each source tuple is mapped to a key, then all keys found in the relation are removed from the source.
     fn filter_anti<'leap, Tuple: Ord, Func: Fn(&Tuple) -> (Key, Val)>(
         &'leap self,
         key_func: Func,
@@ -365,7 +375,9 @@ pub(crate) mod extend_with {
     use super::{binary_search, Leaper, Leapers, Relation};
     use crate::join::gallop;
 
-    /// Wraps a Relation<Tuple> as a leaper.
+    /// Wraps a `Relation<Tuple>` as a [`Leaper`] that maps each source tuple to a key and adds the relation's corresponding values.
+    ///
+    /// This struct is created using the [`extend_with`](`crate::RelationLeaper::extend_with`) method on [`Relation`s](Relation).
     pub struct ExtendWith<'leap, Key, Val, Tuple, Func>
     where
         Key: Ord + 'leap,
@@ -464,7 +476,9 @@ pub(crate) mod extend_anti {
     use super::{binary_search, Leaper, Relation};
     use crate::join::gallop;
 
-    /// Wraps a Relation<Tuple> as a leaper.
+    /// Wraps a `Relation<Tuple>` as a [`Leaper`] that maps each source tuple to a key and removes the relation's corresponding values.
+    ///
+    /// This struct is created using the [`extend_anti`](`crate::RelationLeaper::extend_anti`) method on [`Relation`s](Relation).
     pub struct ExtendAnti<'leap, Key, Val, Tuple, Func>
     where
         Key: Ord + 'leap,
@@ -543,7 +557,9 @@ pub(crate) mod filter_with {
 
     use super::{Leaper, Leapers, Relation};
 
-    /// Wraps a Relation<Tuple> as a leaper.
+    /// Wraps a `Relation<Tuple>` as a [`Leaper`] that keeps only source tuples mapping to a key in the relation.
+    ///
+    /// This struct is created using the [`filter_with`](`crate::RelationLeaper::filter_with`) method on [`Relation`s](Relation).
     pub struct FilterWith<'leap, Key, Val, Tuple, Func>
     where
         Key: Ord + 'leap,
@@ -636,7 +652,9 @@ pub(crate) mod filter_anti {
 
     use super::{Leaper, Leapers, Relation};
 
-    /// Wraps a Relation<Tuple> as a leaper.
+    /// Wraps a `Relation<Tuple>` as a [`Leaper`] that keeps only source tuples not mapping to a key in the relation.
+    ///
+    /// This struct is created using the [`filter_anti`](`crate::RelationLeaper::filter_anti`) method on [`Relation`s](Relation).
     pub struct FilterAnti<'leap, Key, Val, Tuple, Func>
     where
         Key: Ord + 'leap,

src/variable.rs

@@ -251,13 +251,13 @@ impl<Tuple: Ord> Variable<Tuple> {
     ///   You can create a leaper in one of two ways:
     ///   - Extension: In this case, you have a relation of type `(K, Val)` for some
     ///     type `K`. You provide a closure that maps from `SourceTuple` to the key
-    ///     `K`. If you use `relation.extend_with`, then any `Val` values the
+    ///     `K`. If you use [`relation.extend_with`](`crate::RelationLeaper::extend_with`), then any `Val` values the
     ///     relation provides will be added to the set of values; if you use
-    ///     `extend_anti`, then the `Val` values will be removed.
+    ///     [`extend_anti`](`crate::RelationLeaper::extend_anti`), then the `Val` values will be removed.
     ///   - Filtering: In this case, you have a relation of type `K` for some
     ///     type `K` and you provide a closure that maps from `SourceTuple` to
     ///     the key `K`. Filters don't provide values but they remove source
-    ///     tuples.
+    ///     tuples. [`filter_with`](`crate::RelationLeaper::filter_with`) retains matching keys, whereas [`filter_anti`](`crate::RelationLeaper::filter_anti`) removes matching keys.
     /// - Finally, you get a callback `logic` that accepts each `(SourceTuple, Val)`
     ///   that was successfully joined (and not filtered) and which maps to the
     ///   type of this variable.