Documented

src/state.rs

@@ -1,3 +1,8 @@
+//! # State Management Module
+//!
+//! Provides React-like hooks for managing component state and side effects.
+//! This module includes useState, useEffect, useMount, and state synchronization hooks.
+
 use std::{
     any::Any,
     fmt::{Debug, Display, Formatter, Result as FmtResult},
@@ -7,24 +12,42 @@ use std::{
 
 use crate::component::context::Context;
 
+/// Effect callback that can be triggered by state changes
 #[derive(Clone)]
 pub struct HookEffect(Arc<Mutex<dyn FnMut() + Send + Sync>>);
 
+/// State holder for reactive values
+///
+/// Similar to React's useState hook. Holds a value and tracks dependents
+/// that need to be notified when the value changes.
 #[derive(Debug)]
 pub struct State<T> {
+    /// The actual state value
     value: Arc<Mutex<T>>,
+    /// Functions to call when state is updated
     dependents: Arc<Mutex<Vec<HookEffect>>>,
 }
 
+/// Guard for accessing and potentially modifying state
+///
+/// Dereferences to the state value. When dropped after modification,
+/// automatically triggers all dependent effects.
 pub struct Inner<'a, T> {
     value: MutexGuard<'a, T>,
     dependents: Arc<Mutex<Vec<HookEffect>>>,
     updated: bool,
 }
 
+/// Mount lifecycle hook
+///
+/// Tracks whether a component has been mounted and executes
+/// any pending mount effects.
 #[derive(Debug, Clone)]
 pub struct Mount(Arc<Mutex<bool>>, Arc<Mutex<Vec<HookEffect>>>);
 
+/// Creates a new state value
+///
+/// Returns a State that can be read and written from multiple threads.
 pub fn use_state<T>(v: T) -> State<T> {
     State {
         value: Arc::new(Mutex::new(v)),
@@ -33,14 +56,20 @@ pub fn use_state<T>(v: T) -> State<T> {
 }
 
 impl<T: Clone> State<T> {
-    /// Gets the cloned value, recommended for preventing deadlocks
+    /// Gets a cloned copy of the state value
+    ///
+    /// Recommended over `get()` to prevent deadlocks when cloning is acceptable.
+    /// "dl" stands for "deadlock-less".
     pub fn get_dl(&self) -> T {
         self.value.lock().unwrap().clone()
     }
 }
 
 impl<T> State<T> {
-    /// Gets a lock on the state for read/write access.
+    /// Acquires a lock on the state for read/write access
+    ///
+    /// Returns an Inner guard that implements Deref and DerefMut.
+    /// When dropped after modification, triggers dependent effects.
     pub fn get(&self) -> Inner<'_, T> {
         Inner {
             value: self.value.lock().unwrap(),
@@ -49,18 +78,20 @@ impl<T> State<T> {
         }
     }
 
-    /// Sets the value and marks it as changed.
+    /// Sets the state value and triggers dependents
     pub fn set(&self, v: T) {
         *self.value.lock().unwrap() = v;
         self.update();
     }
 
+    /// Notifies all dependents of an update
     pub fn update(&self) {
         for d in self.dependents.lock().unwrap().iter() {
             d.call();
         }
     }
 
+    /// Clones the State handle (not the value)
     pub fn clone(&self) -> Self {
         Self {
             dependents: self.dependents.clone(),
@@ -82,15 +113,19 @@ impl Debug for HookEffect {
 }
 
 impl HookEffect {
+    /// Creates a new effect from a function
     pub fn new<F: Fn() + Send + Sync + 'static>(f: F) -> Self {
         Self(Arc::new(Mutex::new(f)))
     }
 
+    /// Executes the effect function
     pub fn call(&self) {
         (self.0.lock().unwrap())()
     }
 }
 
+/// Inner implements Deref for read access and DerefMut for write access
+/// On drop after mutation, automatically triggers dependent effects
 impl<T> Drop for Inner<'_, T> {
     fn drop(&mut self) {
         if self.updated {
@@ -115,7 +150,9 @@ impl<T> DerefMut for Inner<'_, T> {
     }
 }
 
+/// Trait for values that can be tracked as dependencies in hooks
 pub trait HookDependency: Send + Sync {
+    /// Register an effect to be triggered on updates
     fn on_update(&self, hook: HookEffect);
 }
 
@@ -136,6 +173,7 @@ impl HookDependency for Mount {
 }
 
 impl Mount {
+    /// Mark the component as mounted and execute pending effects
     pub fn mount(&self) {
         *self.0.lock().unwrap() = true;
         for hook_effect in self.1.lock().unwrap().iter() {
@@ -145,6 +183,10 @@ impl Mount {
     }
 }
 
+/// Executes a function when dependencies change
+///
+/// Similar to React's useEffect. The provided function is executed
+/// when any of the dependencies change.
 pub fn use_effect<F: FnMut() + Send + Sync + 'static>(f: F, dependencies: &[&dyn HookDependency]) {
     let f = Arc::new(Mutex::new(f));
     let hook = HookEffect(Arc::new(Mutex::new({
@@ -160,10 +202,18 @@ pub fn use_effect<F: FnMut() + Send + Sync + 'static>(f: F, dependencies: &[&dyn
     }
 }
 
+/// Creates a mount lifecycle hook
+///
+/// Returns a Mount that tracks component lifecycle and executes
+/// effects after mounting.
 pub fn use_mount() -> Mount {
     Mount(Arc::new(Mutex::new(true)), Arc::new(Mutex::new(Vec::new())))
 }
 
+/// Creates a manual mount lifecycle hook
+///
+/// Similar to use_mount but the component starts as unmounted.
+/// Must call .mount() to trigger mounted effects.
 pub fn use_mount_manual() -> Mount {
     Mount(
         Arc::new(Mutex::new(false)),
@@ -171,6 +221,10 @@ pub fn use_mount_manual() -> Mount {
     )
 }
 
+/// Synchronizes state with events from the context
+///
+/// Creates state that is automatically updated when events are emitted
+/// to the context. The decoder function converts events to state values.
 pub fn use_sync_state<
     T: Send + Sync + 'static,
     E: Any + 'static,
@@ -190,6 +244,10 @@ pub fn use_sync_state<
     state
 }
 
+/// Synchronizes state changes back to the context as events
+///
+/// Creates an effect that emits an event whenever the state changes.
+/// The encoder function converts state values to events.
 pub fn use_sync_effect<
     T: Send + Sync + 'static,
     Ev: Send + Sync + 'static,