flow docs

src/flow.rs

@@ -1 +1,3 @@
+//! Data structures and algorithms, independent of [crate::core] concepts.
+
 pub mod traversible;

src/flow/traversible.rs

@@ -1,9 +1,14 @@
+//! Traversible binary trees.
+
 use std::rc::Rc;
 
 use crate::func::*;
 
+/// Result returned by [`Comparator::pick_smaller`].
+#[derive(Debug, PartialEq)]
 pub enum Comparison {
     L,
+    /// Compared values were equal.
     E,
     R,
 }
@@ -12,10 +17,33 @@ fn and(left: bool, right: bool) -> bool {
     left && right
 }
 
+/// Returns [`Comparison`] saying which value is smaller.
+///
+/// ```rust
+/// # use radn_rs::flow::traversible::*;
+/// assert_eq!(DefaultComparator.pick_smaller(&1, &3), Comparison::L);
+/// assert_eq!(DefaultComparator.pick_smaller(&2, &2), Comparison::E);
+/// assert_eq!(DefaultComparator.pick_smaller(&3, &1), Comparison::R);
+/// ```
 pub trait Comparator<A> {
     fn pick_smaller(&self, kl: &A, kr: &A) -> Comparison;
 }
 
+/// Implementation of a [Comparator] relying on [`PartialOrd`].
+pub struct DefaultComparator;
+
+impl<A: PartialOrd> Comparator<A> for DefaultComparator {
+    fn pick_smaller(&self, kl: &A, kr: &A) -> Comparison {
+        if kl < kr {
+            Comparison::L
+        } else if kr < kl {
+            Comparison::R
+        } else {
+            Comparison::E
+        }
+    }
+}
+
 pub type Split<'a, T, A, D> = (
     Rc<dyn TraversibleBinaryTree<'a, T, A, D>>,
     Rc<dyn TraversibleBinaryTree<'a, T, A, D>>,

src/func.rs

@@ -20,6 +20,7 @@ pub mod tests;
 ///
 /// <https://hackage.haskell.org/package/base-4.18.0.0/docs/Data-Functor.html>
 pub trait WeakFunctor {
+    /// Type of the wrapped value.
     type F<'a, A: 'a>: 'a
     where
         Self: 'a;
@@ -233,10 +234,15 @@ pub trait LocalFunctor: WeakFunctor {
         Self: 'a;
 }
 
+/// Represents a (collection of) [Monad]\(s) that can hold any type of error.
 pub trait MonadFailAny {
+    /// [`MonadFail`] for a specific error type.
     type W<E>: MonadFail<E>;
 }
 
+/// Represents a (collection of) [Monad]\(s),
+/// wrapped values of which are interchangeable with another [Monad]'s
+/// wrapped [Result]s.
 pub trait MonadFailOver<T: Monad>: MonadFailAny {
     fn unstuff<'a, A: 'a, E: 'a>(
         wa: <Self::W<E> as WeakFunctor>::F<'a, A>,

src/std.rs

@@ -36,13 +36,19 @@ impl<S: Serializable> ExtSerializable for S {
     }
 }
 
-pub trait ExtContext: Context {
+/// Extention trait for simpler conversion between [`Context::T`] and [`Context::Fallible`].
+/// 
+/// Until either Rust type system or [`crate::func`] take serious changes,
+/// this is the preferred way to switch between [Wrapped] and [fallible].
+pub trait FallibleContext: Context {
+    /// Convert a fallible wrapped into a wrapped result.
     fn unstuff<'a, A: 'a, E: 'a>(
         wa: <<Self::Fallible as MonadFailAny>::W<E> as WeakFunctor>::F<'a, A>,
     ) -> <Self::T as WeakFunctor>::F<'a, Result<A, E>>
     where
         Self: 'a;
 
+    /// Convert a wrapped result into a fallible wrapped.
     fn stuff<'a, A: 'a, E: 'a>(
         fa: <Self::T as WeakFunctor>::F<'a, Result<A, E>>,
     ) -> <<Self::Fallible as MonadFailAny>::W<E> as WeakFunctor>::F<'a, A>
@@ -50,7 +56,7 @@ pub trait ExtContext: Context {
         Self: 'a;
 }
 
-impl<Ctx: Context> ExtContext for Ctx {
+impl<Ctx: Context> FallibleContext for Ctx {
     fn unstuff<'a, A: 'a, E: 'a>(
         wa: <<Self::Fallible as MonadFailAny>::W<E> as WeakFunctor>::F<'a, A>,
     ) -> <Self::T as WeakFunctor>::F<'a, Result<A, E>>