document signals crate

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())
     }