Add documentation and comments

Author: fxdmhtt

cache/src/effect.rs

@@ -1,5 +1,23 @@
 use std::rc::Rc;
 
+/// A reactive effect that runs a closure whenever its dependencies change.
+///
+/// `Effect<F>` behaves similarly to an "event listener" or a callback,
+/// but it is automatically tied to any signals or memos it reads during execution.
+/// When those dependencies change, the effect will re-run.
+///
+/// Note: The closure runs **immediately upon creation** via `Effect::wrap`,
+/// so the effect is always initialized with an up-to-date value.
+///
+/// In short:
+/// - Like a callback: wraps a closure of type `F` and runs it.
+/// - Adds tracking: automatically re-runs when dependent signals change.
+/// - Runs once immediately at creation.
+///
+/// # Type Parameters
+///
+/// - `F`: The closure type wrapped by this effect. Must implement `Fn()`.
+///   The closure is executed immediately upon creation and tracked for reactive updates.
 pub struct Effect<F>
 where
     F: Fn(),
@@ -11,6 +29,28 @@ impl<F> Effect<F>
 where
     F: Fn(),
 {
+    /// Creates a new `Effect`, wrapping the provided closure
+    /// and running it immediately for dependency tracking.
+    ///
+    /// Returns an `Rc<dyn IEffect>` so the effect can be stored and shared
+    /// as a non-generic trait object.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::{cell::Cell, rc::Rc};
+    /// use reactive_cache::Effect;
+    ///
+    /// let counter = Rc::new(Cell::new(0));
+    /// let c_clone = counter.clone();
+    ///
+    /// let effect = Effect::new(move || {
+    ///     // This closure runs immediately
+    ///     c_clone.set(c_clone.get() + 1);
+    /// });
+    ///
+    /// assert_eq!(counter.get(), 1);
+    /// ```
     #[allow(clippy::new_ret_no_self)]
     pub fn new(f: F) -> Rc<dyn IEffect>
     where
@@ -26,7 +66,16 @@ where
     }
 }
 
+/// A non-generic trait for reactive effects.
+///
+/// `IEffect` serves as a type-erased trait for `Effect<F>` instances.
+/// By implementing `IEffect`, an `Effect<F>` can be stored as `Rc<dyn IEffect>`
+/// regardless of the specific closure type `F`. This allows the reactive system
+/// to manage multiple effects uniformly without exposing the generic type.
 pub trait IEffect {
+    /// Runs the effect closure.
+    ///
+    /// Typically called by the reactive system when dependencies change.
     fn run(&self);
 }
 

cache/src/memo.rs

@@ -1,5 +1,19 @@
 use crate::{Observable, call_stack, remove_from_cache, store_in_cache, touch};
 
+/// A memoized reactive computation that caches its result and tracks dependencies.
+///
+/// `Memo<T, F>` behaves similarly to a computed property: it stores the result of a closure
+/// and only recomputes when its dependencies change. Other signals or effects that access
+/// the memo will automatically be tracked.
+///
+/// In short:
+/// - Like a computed property: returns a cached value derived from other signals.
+/// - Adds tracking: recomputes only when dependencies are invalidated.
+///
+/// # Type Parameters
+///
+/// - `T`: The result type of the computation. Must implement `Clone`.
+/// - `F`: The closure type that computes the value. Must implement `Fn() -> T`.
 pub struct Memo<T, F>
 where
     F: Fn() -> T,
@@ -22,13 +36,35 @@ impl<T, F> Memo<T, F>
 where
     F: Fn() -> T,
 {
+    /// Creates a new `Memo` wrapping the provided closure.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use reactive_cache::Memo;
+    ///
+    /// let memo = Memo::new(|| 10);
+    /// ```
     pub fn new(f: F) -> Self {
         Memo {
             f,
             dependents: vec![],
         }
     }
 
+    /// Returns the memoized value, recomputing it only if necessary.
+    ///
+    /// During the computation, dependencies are tracked for reactive updates.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use once_cell::unsync::Lazy;
+    /// use reactive_cache::Memo;
+    ///
+    /// static mut MEMO: Lazy<Memo<i32, fn() -> i32>> = Lazy::new(|| Memo::new(|| 5));
+    /// assert_eq!(unsafe { (*MEMO).get() }, 5);
+    /// ```
     pub fn get(&'static mut self) -> T
     where
         T: Clone,

cache/src/signal.rs

@@ -5,17 +5,34 @@ use std::{
 
 use crate::{IEffect, Observable, call_stack};
 
+/// A reactive signal that holds a value, tracks dependencies, and triggers effects.
+///
+/// `Signal<T>` behaves similarly to a traditional "Property" (getter/setter),
+/// but on top of that, it automatically tracks which reactive computations
+/// or effects access it. When its value changes, all dependent effects
+/// are automatically re-run.
+///
+/// In short:
+/// - Like a Property: provides `get()` and `set()` for accessing and updating the value.
+/// - Adds tracking: automatically records dependencies when read inside reactive contexts,
+///   and automatically triggers dependent `Effect`s when updated.
+///
+/// # Type Parameters
+///
+/// - `T`: The type of the value stored in the signal. Must implement `Eq + Default`.
 pub struct Signal<T> {
     value: RefCell<T>,
     dependents: RefCell<Vec<&'static dyn Observable>>,
     effects: RefCell<Vec<Weak<dyn IEffect>>>,
 }
 
 impl<T> Signal<T> {
+    /// Invalidates all dependent observables.
     fn invalidate(&self) {
         self.dependents.borrow().iter().for_each(|d| d.invalidate());
     }
 
+    /// Runs all dependent effects.
     fn flush_effects(&self) {
         self.effects.borrow_mut().retain(|w| {
             if let Some(e) = w.upgrade() {
@@ -37,6 +54,21 @@ impl<T> Signal<T> {
         self.invalidate()
     }
 
+    /// Creates a new `Signal` with the given initial value.
+    ///
+    /// If `None` is provided, `T::default()` is used.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use reactive_cache::Signal;
+    ///
+    /// let signal = Signal::new(Some(10));
+    /// assert_eq!(*signal.get(), 10);
+    ///
+    /// let default_signal: Signal<i32> = Signal::new(None);
+    /// assert_eq!(*default_signal.get(), 0);
+    /// ```
     pub fn new(value: Option<T>) -> Self
     where
         T: Default,
@@ -48,7 +80,18 @@ impl<T> Signal<T> {
         }
     }
 
+    /// Gets a reference to the current value, tracking dependencies and effects if inside a reactive context.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use reactive_cache::Signal;
+    ///
+    /// let signal = Signal::new(Some(42));
+    /// assert_eq!(*signal.get(), 42);
+    /// ```
     pub fn get(&self) -> Ref<'_, T> {
+        // Track observables in the call stack
         if let Some(last) = call_stack::last()
             && !self
                 .dependents
@@ -59,6 +102,7 @@ impl<T> Signal<T> {
             self.dependents.borrow_mut().push(*last);
         }
 
+        // Track effects in the call stack
         if let Some(e) = call_stack::creating_effect_peak()
             && !self.effects.borrow().iter().any(|w| Weak::ptr_eq(w, &e))
         {
@@ -68,6 +112,22 @@ impl<T> Signal<T> {
         self.value.borrow()
     }
 
+    /// Sets the value of the signal.
+    ///
+    /// Returns `true` if the value changed and dependent effects were triggered.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use reactive_cache::Signal;
+    ///
+    /// let signal = Signal::new(Some(5));
+    /// assert_eq!(signal.set(10), true);
+    /// assert_eq!(*signal.get(), 10);
+    ///
+    /// // Setting to the same value returns false
+    /// assert_eq!(signal.set(10), false);
+    /// ```
     pub fn set(&self, value: T) -> bool
     where
         T: Eq,