Merge pull request #360 from marvin-hansen/main

Added documentation to HAFT crate

Author: marvin-hansen

README.md

@@ -166,6 +166,7 @@ make example
 * `deep_causality_algorithms`: Provides algorithms for the DeepCausality library.
 * `deep_causality_data_structures`: Provides data structures for the DeepCausality library.
 * `deep_causality_discovery`: A custom DSL for causal discovery.
+* `deep_causality_haft`: Higher-Order Abstract Functional Traits a.k.a HKT. 
 * `deep_causality_macros`: Provides macros for the DeepCausality library (_deprecated_).
 * `deep_causality_num`: Numerical traits and utils used across the other crates.
 * `deep_causality_rand`: Random number generator and statistical distributions used in deep_causality_tensor and other

deep_causality_haft/BUILD.bazel

@@ -29,9 +29,3 @@ rust_doc_test(
     tags = ["doc-test"],
     visibility = ["//visibility:public"],
 )
-
-rust_test(
-    name = "tests",
-    srcs = glob(["tests/**"]),
-    crate = ":deep_causality_haft",
-)

deep_causality_haft/src/applicative.rs

@@ -4,15 +4,66 @@
  */
 use crate::{Functor, HKT};
 
-/// Applicative: Abstracts over the ability to apply a function wrapped in a context
-/// to a value wrapped in a context.
+/// The `Applicative` trait extends `Functor` by providing methods to apply a function
+/// wrapped in a context to a value wrapped in a context, and to lift a pure value
+/// into the minimal context.
 ///
-/// Generic over the HKT witness `F`.
+/// This trait is generic over `F`, which is a Higher-Kinded Type (HKT) witness.
+///
+/// # Laws (Informal)
+///
+/// 1.  **Identity**: `pure(id).apply(v) == v`
+/// 2.  **Homomorphism**: `pure(f).apply(pure(x)) == pure(f(x))`
+/// 3.  **Interchange**: `u.apply(pure(y)) == pure(|f| f(y)).apply(u)`
+///
+/// # Type Parameters
+///
+/// *   `F`: A Higher-Kinded Type (HKT) witness that represents the type constructor
+///     (e.g., `OptionWitness`, `ResultWitness<E>`).
 pub trait Applicative<F: HKT>: Functor<F> {
-    /// Lifts a pure value into the minimal applicative context.
+    /// Lifts a pure value into the minimal applicative context `F::Type<T>`.
+    ///
+    /// This is often used to introduce a value into an effectful computation
+    /// without any side effects.
+    ///
+    /// # Arguments
+    ///
+    /// *   `value`: The pure value to lift.
+    ///
+    /// # Returns
+    ///
+    /// An instance of `F::Type<T>` containing the `value`.
+    ///
+    /// # Examples
+    ///
+    ///
     fn pure<T>(value: T) -> F::Type<T>;
 
-    /// Applies a function wrapped in a context to a value wrapped in a context.
+    /// Applies a function wrapped in a context (`f_ab`) to a value wrapped in a context (`f_a`).
+    ///
+    /// This allows sequencing computations where both the function and its argument
+    /// are within the same applicative context.
+    ///
+    /// # Arguments
+    ///
+    /// *   `f_ab`: An instance of `F::Type<Func>` containing the function to apply.
+    /// *   `f_a`: An instance of `F::Type<A>` containing the argument for the function.
+    ///
+    /// # Returns
+    ///
+    /// An instance of `F::Type<B>` containing the result of the application,
+    /// or an appropriate error/empty context if either `f_ab` or `f_a` is in an
+    /// error/empty state.
+    ///
+    /// # Type Parameters
+    ///
+    /// *   `A`: The input type of the function.
+    /// *   `B`: The output type of the function.
+    /// *   `Func`: The type of the function, which must be `FnMut(A) -> B`.
+    ///
+    /// # Examples
+    ///
+    ///
     fn apply<A, B, Func>(f_ab: F::Type<Func>, f_a: F::Type<A>) -> F::Type<B>
     where
         Func: FnMut(A) -> B,

deep_causality_haft/src/effect.rs

@@ -12,36 +12,47 @@ use crate::{HKT, HKT3, HKT4, HKT5};
 /// Effect3: The Bridge Trait for Arity 3 Type Constructors.
 ///
 /// This trait is implemented by a user-defined **System Witness** (e.g., `MyEffect`)
-/// to partially apply (fix) two of the three generic parameters of the HKT3 type.
+/// to partially apply (fix) two of the three generic parameters of an `HKT3` type.
+/// It serves as a crucial component in building type-encoded effect systems,
+/// allowing for the explicit tracking and handling of two fixed effect types
+/// (e.g., Error and Warning) while keeping the primary value type generic.
 pub trait Effect3 {
-    /// The fixed type for the first parameter (e.g., the Error type E).
+    /// The fixed type for the first parameter of the `HKT3` type.
+    /// In many effect systems, this represents the Error type (e.g., `String`, `MyErrorStruct`).
     type Fixed1;
 
-    /// The fixed type for the second parameter (e.g., the Warning/Log type W).
+    /// The fixed type for the second parameter of the `HKT3` type.
+    /// This often represents a Warning or Log type (e.g., `String`, `Vec<String>`).
     type Fixed2;
 
-    /// The concrete witness type that implements HKT3 with the two fixed types.
-    /// It MUST implement HKT so we can pass it to Functor/Monad functions.
+    /// The concrete witness type that implements `HKT3` with the two fixed types (`Fixed1`, `Fixed2`).
+    /// This witness type *MUST* also implement `HKT` to be compatible with `Functor` and `Monad` traits.
+    /// It acts as a token to refer to the partially applied type constructor.
     type HktWitness: HKT3<Self::Fixed1, Self::Fixed2> + HKT;
 }
 
 // ----------------------------------------------------
 // Effect Traits (Arity 4)
 // ----------------------------------------------------
 
-/// Effect4: The Bridge Trait for Arity 4 Type Constructors.I
+/// Effect4: The Bridge Trait for Arity 4 Type Constructors.
+///
+/// Similar to `Effect3`, this trait is implemented by a user-defined **System Witness**
+/// to partially apply (fix) three of the four generic parameters of an `HKT4` type.
+/// It is used for effect systems that need to track three distinct fixed effect types
+/// (e.g., Error, Warning, and a Counter) alongside the primary value type.
 pub trait Effect4 {
-    /// The fixed type for the first parameter.
+    /// The fixed type for the first parameter of the `HKT4` type (e.g., an Error type).
     type Fixed1;
 
-    /// The fixed type for the second parameter.
+    /// The fixed type for the second parameter of the `HKT4` type (e.g., a Log type).
     type Fixed2;
 
-    /// The fixed type for the third parameter.
+    /// The fixed type for the third parameter of the `HKT4` type (e.g., a Counter type).
     type Fixed3;
 
-    /// The concrete witness type that implements HKT4 with the three fixed types.
-    /// It MUST implement HKT so we can pass it to Functor/Monad functions.
+    /// The concrete witness type that implements `HKT4` with the three fixed types (`Fixed1`, `Fixed2`, `Fixed3`).
+    /// This witness type *MUST* also implement `HKT` to be compatible with `Functor` and `Monad` traits.
     type HktWitness: HKT4<Self::Fixed1, Self::Fixed2, Self::Fixed3> + HKT;
 }
 
@@ -50,12 +61,25 @@ pub trait Effect4 {
 // ----------------------------------------------------
 
 /// Effect5: The Bridge Trait for Arity 5 Type Constructors.
+///
+/// This trait is implemented by a user-defined **System Witness**
+/// to partially apply (fix) four of the five generic parameters of an `HKT5` type.
+/// It is designed for highly expressive effect systems that need to track four distinct fixed effect types
+/// (e.g., Error, Warning, Counter, and Trace information) alongside the primary value type.
 pub trait Effect5 {
+    /// The fixed type for the first parameter of the `HKT5` type (e.g., an Error type).
     type Fixed1;
+
+    /// The fixed type for the second parameter of the `HKT5` type (e.g., a Log type).
     type Fixed2;
+
+    /// The fixed type for the third parameter of the `HKT5` type (e.g., a Counter type).
     type Fixed3;
+
+    /// The fixed type for the fourth parameter of the `HKT5` type (e.g., a Trace type).
     type Fixed4;
 
-    /// The concrete witness type that implements HKT5 with the four fixed types.
+    /// The concrete witness type that implements `HKT5` with the four fixed types (`Fixed1`, `Fixed2`, `Fixed3`, `Fixed4`).
+    /// This witness type *MUST* also implement `HKT` to be compatible with `Functor` and `Monad` traits.
     type HktWitness: HKT5<Self::Fixed1, Self::Fixed2, Self::Fixed3, Self::Fixed4> + HKT;
 }

deep_causality_haft/src/extensions/hkt_option_ext.rs

@@ -5,15 +5,34 @@
 
 use crate::{Applicative, Foldable, Functor, HKT, Monad};
 
-// Witness for Option
+/// `OptionWitness` is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness
+/// for the `Option<T>` type constructor. It allows `Option` to be used with generic
+/// functional programming traits like `Functor`, `Applicative`, `Foldable`, and `Monad`.
+///
+/// By implementing `HKT` for `OptionWitness`, we can write generic functions that operate
+/// on any type that has the "shape" of `Option`, without knowing the inner type `T`.
 pub struct OptionWitness;
 
 impl HKT for OptionWitness {
+    /// Specifies that `OptionWitness` represents the `Option<T>` type constructor.
     type Type<T> = Option<T>;
 }
 
 // Implementation of Functor for OptionWitness
 impl Functor<OptionWitness> for OptionWitness {
+    /// Implements the `fmap` operation for `Option<T>`.
+    ///
+    /// If the `Option` is `Some(value)`, the function `f` is applied to `value`,
+    /// and the result is wrapped in `Some`. If the `Option` is `None`, `None` is returned.
+    ///
+    /// # Arguments
+    ///
+    /// *   `m_a`: The `Option` to map over.
+    /// *   `f`: The function to apply to the value inside the `Option`.
+    ///
+    /// # Returns
+    ///
+    /// A new `Option` with the function applied to its content, or `None`.
     fn fmap<A, B, Func>(
         m_a: <OptionWitness as HKT>::Type<A>,
         f: Func,
@@ -27,10 +46,32 @@ impl Functor<OptionWitness> for OptionWitness {
 
 // Implementation of Applicative for OptionWitness
 impl Applicative<OptionWitness> for OptionWitness {
+    /// Lifts a pure value into a `Some` variant of `Option`.
+    ///
+    /// # Arguments
+    ///
+    /// *   `value`: The value to wrap in `Some`.
+    ///
+    /// # Returns
+    ///
+    /// `Some(value)`.
     fn pure<T>(value: T) -> <OptionWitness as HKT>::Type<T> {
         Some(value)
     }
 
+    /// Applies a function wrapped in an `Option` (`f_ab`) to a value wrapped in an `Option` (`f_a`).
+    ///
+    /// If both `f_ab` and `f_a` are `Some`, the function is applied to the value.
+    /// If either is `None`, `None` is returned.
+    ///
+    /// # Arguments
+    ///
+    /// *   `f_ab`: An `Option` containing the function.
+    /// *   `f_a`: An `Option` containing the argument.
+    ///
+    /// # Returns
+    ///
+    /// An `Option` containing the result of the application, or `None`.
     fn apply<A, B, Func>(
         f_ab: <OptionWitness as HKT>::Type<Func>,
         f_a: <OptionWitness as HKT>::Type<A>,
@@ -44,6 +85,21 @@ impl Applicative<OptionWitness> for OptionWitness {
 
 // Implementation of Foldable for OptionWitness
 impl Foldable<OptionWitness> for OptionWitness {
+    /// Folds (reduces) an `Option` into a single value.
+    ///
+    /// If the `Option` is `Some(value)`, the function `f` is applied with the initial
+    /// accumulator and the `value`. If the `Option` is `None`, the initial accumulator
+    /// is returned.
+    ///
+    /// # Arguments
+    ///
+    /// *   `fa`: The `Option` to fold.
+    /// *   `init`: The initial accumulator value.
+    /// *   `f`: The folding function.
+    ///
+    /// # Returns
+    ///
+    /// The accumulated result.
     fn fold<A, B, Func>(fa: Option<A>, init: B, mut f: Func) -> B
     where
         Func: FnMut(B, A) -> B,
@@ -57,6 +113,20 @@ impl Foldable<OptionWitness> for OptionWitness {
 
 // Implementation of Monad for OptionWitness
 impl Monad<OptionWitness> for OptionWitness {
+    /// Implements the `bind` (or `and_then`) operation for `Option<T>`.
+    ///
+    /// If the `Option` is `Some(value)`, the function `f` is applied to `value`,
+    /// which itself returns an `Option`. If the `Option` is `None`, `None` is returned.
+    /// This effectively chains computations that might fail.
+    ///
+    /// # Arguments
+    ///
+    /// *   `m_a`: The initial `Option`.
+    /// *   `f`: A function that takes the inner value of `m_a` and returns a new `Option`.
+    ///
+    /// # Returns
+    ///
+    /// A new `Option` representing the chained computation.
     fn bind<A, B, Func>(
         m_a: <OptionWitness as HKT>::Type<A>,
         f: Func,