document signals crate

packages/signals/src/effect.rs

@@ -20,6 +20,13 @@ pub(crate) fn get_effect_stack() -> EffectStack {
     }
 }
 
+/// Create a new effect. The effect will be run immediately and whenever any signal it reads changes.
+/// The signal will be owned by the current component and will be dropped when the component is dropped.
+pub fn use_effect(cx: &ScopeState, callback: impl FnMut() + 'static) {
+    cx.use_hook(|| Effect::new(callback));
+}
+
+/// Effects allow you to run code when a signal changes. Effects are run immediately and whenever any signal it reads changes.
 #[derive(Copy, Clone, PartialEq)]
 pub struct Effect {
     pub(crate) callback: CopyValue<Box<dyn FnMut()>>,
@@ -36,6 +43,9 @@ impl Effect {
         get_effect_stack().effects.read().last().copied()
     }
 
+    /// Create a new effect. The effect will be run immediately and whenever any signal it reads changes.
+    ///
+    /// The signal will be owned by the current component and will be dropped when the component is dropped.
     pub fn new(callback: impl FnMut() + 'static) -> Self {
         let myself = Self {
             callback: CopyValue::new(Box::new(callback)),

packages/signals/src/impls.rs

@@ -43,6 +43,7 @@ macro_rules! read_impls {
         }
 
         impl<T: 'static> $ty<Option<T>> {
+            /// Unwraps the inner value and clones it.
             pub fn unwrap(&self) -> T
             where
                 T: Clone,
@@ -50,6 +51,7 @@ macro_rules! read_impls {
                 self.with(|v| v.clone()).unwrap()
             }
 
+            /// Attemps to read the inner value of the Option.
             pub fn as_ref(&self) -> Option<Ref<'_, T>> {
                 Ref::filter_map(self.read(), |v| v.as_ref()).ok()
             }
@@ -59,6 +61,14 @@ macro_rules! read_impls {
 
 macro_rules! write_impls {
     ($ty:ident) => {
+        impl<T: Add<Output = T> + Copy + 'static> std::ops::Add<T> for $ty<T> {
+            type Output = T;
+
+            fn add(self, rhs: T) -> Self::Output {
+                self.with(|v| *v + rhs)
+            }
+        }
+
         impl<T: Add<Output = T> + Copy + 'static> std::ops::AddAssign<T> for $ty<T> {
             fn add_assign(&mut self, rhs: T) {
                 self.with_mut(|v| *v = *v + rhs)
@@ -71,73 +81,111 @@ macro_rules! write_impls {
             }
         }
 
+        impl<T: Sub<Output = T> + Copy + 'static> std::ops::Sub<T> for $ty<T> {
+            type Output = T;
+
+            fn sub(self, rhs: T) -> Self::Output {
+                self.with(|v| *v - rhs)
+            }
+        }
+
         impl<T: Mul<Output = T> + Copy + 'static> std::ops::MulAssign<T> for $ty<T> {
             fn mul_assign(&mut self, rhs: T) {
                 self.with_mut(|v| *v = *v * rhs)
             }
         }
 
+        impl<T: Mul<Output = T> + Copy + 'static> std::ops::Mul<T> for $ty<T> {
+            type Output = T;
+
+            fn mul(self, rhs: T) -> Self::Output {
+                self.with(|v| *v * rhs)
+            }
+        }
+
         impl<T: Div<Output = T> + Copy + 'static> std::ops::DivAssign<T> for $ty<T> {
             fn div_assign(&mut self, rhs: T) {
                 self.with_mut(|v| *v = *v / rhs)
             }
         }
 
+        impl<T: Div<Output = T> + Copy + 'static> std::ops::Div<T> for $ty<T> {
+            type Output = T;
+
+            fn div(self, rhs: T) -> Self::Output {
+                self.with(|v| *v / rhs)
+            }
+        }
+
         impl<T: 'static> $ty<Vec<T>> {
+            /// Pushes a new value to the end of the vector.
             pub fn push(&self, value: T) {
                 self.with_mut(|v| v.push(value))
             }
 
+            /// Pops the last value from the vector.
             pub fn pop(&self) -> Option<T> {
                 self.with_mut(|v| v.pop())
             }
 
+            /// Inserts a new value at the given index.
             pub fn insert(&self, index: usize, value: T) {
                 self.with_mut(|v| v.insert(index, value))
             }
 
+            /// Removes the value at the given index.
             pub fn remove(&self, index: usize) -> T {
                 self.with_mut(|v| v.remove(index))
             }
 
+            /// Clears the vector, removing all values.
             pub fn clear(&self) {
                 self.with_mut(|v| v.clear())
             }
 
+            /// Extends the vector with the given iterator.
             pub fn extend(&self, iter: impl IntoIterator<Item = T>) {
                 self.with_mut(|v| v.extend(iter))
             }
 
+            /// Truncates the vector to the given length.
             pub fn truncate(&self, len: usize) {
                 self.with_mut(|v| v.truncate(len))
             }
 
+            /// Swaps two values in the vector.
             pub fn swap_remove(&self, index: usize) -> T {
                 self.with_mut(|v| v.swap_remove(index))
             }
 
+            /// Retains only the values that match the given predicate.
             pub fn retain(&self, f: impl FnMut(&T) -> bool) {
                 self.with_mut(|v| v.retain(f))
             }
 
+            /// Splits the vector into two at the given index.
             pub fn split_off(&self, at: usize) -> Vec<T> {
                 self.with_mut(|v| v.split_off(at))
             }
         }
 
         impl<T: 'static> $ty<Option<T>> {
+            /// Takes the value out of the Option.
             pub fn take(&self) -> Option<T> {
                 self.with_mut(|v| v.take())
             }
 
+            /// Replace the value in the Option.
             pub fn replace(&self, value: T) -> Option<T> {
                 self.with_mut(|v| v.replace(value))
             }
 
+            /// Gets the value out of the Option, or inserts the given value if the Option is empty.
             pub fn get_or_insert(&self, default: T) -> Ref<'_, T> {
                 self.get_or_insert_with(|| default)
             }
 
+            /// Gets the value out of the Option, or inserts the value returned by the given function if the Option is empty.
             pub fn get_or_insert_with(&self, default: impl FnOnce() -> T) -> Ref<'_, T> {
                 let borrow = self.read();
                 if borrow.is_none() {
@@ -158,6 +206,7 @@ read_impls!(Signal);
 write_impls!(Signal);
 read_impls!(ReadOnlySignal);
 
+/// An iterator over the values of a `CopyValue<Vec<T>>`.
 pub struct CopyValueIterator<T: 'static> {
     index: usize,
     value: CopyValue<Vec<T>>,
@@ -198,12 +247,13 @@ impl<T: 'static> CopyValue<Option<T>> {
     }
 }
 
-pub struct CopySignalIterator<T: 'static> {
+/// An iterator over items in a `Signal<Vec<T>>`.
+pub struct SignalIterator<T: 'static> {
     index: usize,
     value: Signal<Vec<T>>,
 }
 
-impl<T: Clone> Iterator for CopySignalIterator<T> {
+impl<T: Clone> Iterator for SignalIterator<T> {
     type Item = T;
 
     fn next(&mut self) -> Option<Self::Item> {
@@ -214,12 +264,12 @@ impl<T: Clone> Iterator for CopySignalIterator<T> {
 }
 
 impl<T: Clone + 'static> IntoIterator for Signal<Vec<T>> {
-    type IntoIter = CopySignalIterator<T>;
+    type IntoIter = SignalIterator<T>;
 
     type Item = T;
 
     fn into_iter(self) -> Self::IntoIter {
-        CopySignalIterator {
+        SignalIterator {
             index: 0,
             value: self,
         }
@@ -227,12 +277,14 @@ impl<T: Clone + 'static> IntoIterator for Signal<Vec<T>> {
 }
 
 impl<T: 'static> Signal<Vec<T>> {
+    /// Returns a reference to an element or `None` if out of bounds.
     pub fn get_mut(&self, index: usize) -> Option<Write<'_, T, Vec<T>>> {
         Write::filter_map(self.write(), |v| v.get_mut(index))
     }
 }
 
 impl<T: 'static> Signal<Option<T>> {
+    /// Returns a reference to an element or `None` if out of bounds.
     pub fn as_mut(&self) -> Option<Write<'_, T, Option<T>>> {
         Write::filter_map(self.write(), |v| v.as_mut())
     }

packages/signals/src/rt.rs

@@ -40,12 +40,18 @@ fn owner_in_scope(scope: ScopeId) -> Rc<Owner> {
     }
 }
 
+/// CopyValue is a wrapper around a value to make the value mutable and Copy.
+///
+/// It is internally backed by [`generational_box::GenerationalBox`].
 pub struct CopyValue<T: 'static> {
     pub(crate) value: GenerationalBox<T>,
     origin_scope: ScopeId,
 }
 
 impl<T: 'static> CopyValue<T> {
+    /// Create a new CopyValue. The value will be stored in the current component.
+    ///
+    /// Once the component this value is created in is dropped, the value will be dropped.
     pub fn new(value: T) -> Self {
         let owner = current_owner();
 

packages/signals/src/selector.rs

@@ -2,6 +2,23 @@ use dioxus_core::prelude::*;
 
 use crate::{get_effect_stack, signal::SignalData, CopyValue, Effect, ReadOnlySignal, Signal};
 
+/// Creates a new Selector. The selector will be run immediately and whenever any signal it reads changes.
+///
+/// Selectors can be used to efficiently compute derived data from signals.
+///
+/// ```rust
+/// use dioxus::prelude::*;
+/// use dioxus_signals::*;
+///
+/// fn App(cx: Scope) -> Element {
+///     let mut count = use_signal(cx, || 0);
+///     let double = use_selector(cx, move || count * 2);
+///     count += 1;
+///     assert_eq!(double.value(), count * 2);
+///  
+///     render! { "{double}" }
+/// }
+/// ```
 pub fn use_selector<R: PartialEq>(
     cx: &ScopeState,
     f: impl FnMut() -> R + 'static,
@@ -9,6 +26,9 @@ pub fn use_selector<R: PartialEq>(
     *cx.use_hook(|| selector(f))
 }
 
+/// Creates a new Selector. The selector will be run immediately and whenever any signal it reads changes.
+///
+/// Selectors can be used to efficiently compute derived data from signals.
 pub fn selector<R: PartialEq>(mut f: impl FnMut() -> R + 'static) -> ReadOnlySignal<R> {
     let state = Signal::<R> {
         inner: CopyValue::invalid(),

packages/signals/src/signal.rs

@@ -12,6 +12,37 @@ use dioxus_core::{
 
 use crate::{CopyValue, Effect};
 
+/// Creates a new Signal. Signals are a Copy state management solution with automatic dependency tracking.
+///
+/// ```rust
+/// use dioxus::prelude::*;
+/// use dioxus_signals::*;
+///
+/// fn App(cx: Scope) -> Element {
+///     let mut count = use_signal(cx, || 0);
+///
+///     // Because signals have automatic dependency tracking, if you never read them in a component, that component will not be re-rended when the signal is updated.
+///     // The app component will never be rerendered in this example.
+///     render! { Child { state: count } }
+/// }
+///
+/// #[inline_props]
+/// fn Child(cx: Scope, state: Signal<u32>) -> Element {
+///     let state = *state;
+///
+///     use_future!(cx,  |()| async move {
+///         // Because the signal is a Copy type, we can use it in an async block without cloning it.
+///         *state.write() += 1;
+///     });
+///
+///     render! {
+///         button {
+///             onclick: move |_| *state.write() += 1,
+///             "{state}"
+///         }
+///     }
+/// }
+/// ```
 pub fn use_signal<T: 'static>(cx: &ScopeState, f: impl FnOnce() -> T) -> Signal<T> {
     *cx.use_hook(|| Signal::new(f()))
 }