add more docs around lifetime downcasting

packages/signals/src/copy_value.rs

@@ -238,8 +238,10 @@ impl<T: 'static, S: Storage<T>> Writable for CopyValue<T, S> {
         S::try_map_mut(mut_, f)
     }
 
-    fn downcast_mut<'a: 'b, 'b, R: ?Sized + 'static>(mut_: Self::Mut<'a, R>) -> Self::Mut<'b, R> {
-        S::downcast_mut(mut_)
+    fn downcast_lifetime_mut<'a: 'b, 'b, R: ?Sized + 'static>(
+        mut_: Self::Mut<'a, R>,
+    ) -> Self::Mut<'b, R> {
+        S::downcast_lifetime_mut(mut_)
     }
 
     #[track_caller]

packages/signals/src/global/signal.rs

@@ -104,7 +104,9 @@ impl<T: 'static> Writable for GlobalSignal<T> {
         Write::filter_map(ref_, f)
     }
 
-    fn downcast_mut<'a: 'b, 'b, R: ?Sized + 'static>(mut_: Self::Mut<'a, R>) -> Self::Mut<'b, R> {
+    fn downcast_lifetime_mut<'a: 'b, 'b, R: ?Sized + 'static>(
+        mut_: Self::Mut<'a, R>,
+    ) -> Self::Mut<'b, R> {
         Write::downcast_lifetime(mut_)
     }
 

packages/signals/src/read.rs

@@ -53,7 +53,8 @@ pub trait Readable {
     /// Try to get the current value of the state. If this is a signal, this will subscribe the current scope to the signal.
     #[track_caller]
     fn try_read(&self) -> Result<ReadableRef<Self>, generational_box::BorrowError> {
-        self.try_read_unchecked().map(Self::Storage::downcast_ref)
+        self.try_read_unchecked()
+            .map(Self::Storage::downcast_lifetime_ref)
     }
 
     /// Try to get a reference to the value without checking the lifetime.
@@ -80,7 +81,7 @@ pub trait Readable {
     /// Get the current value of the state without subscribing to updates. If the value has been dropped, this will panic.
     #[track_caller]
     fn peek(&self) -> ReadableRef<Self> {
-        Self::Storage::downcast_ref(self.peek_unchecked())
+        Self::Storage::downcast_lifetime_ref(self.peek_unchecked())
     }
 
     /// Clone the inner value and return it. If the value has been dropped, this will panic.

packages/signals/src/signal.rs

@@ -212,7 +212,9 @@ impl<T: 'static, S: Storage<SignalData<T>>> Writable for Signal<T, S> {
         Write::filter_map(ref_, f)
     }
 
-    fn downcast_mut<'a: 'b, 'b, R: ?Sized + 'static>(mut_: Self::Mut<'a, R>) -> Self::Mut<'b, R> {
+    fn downcast_lifetime_mut<'a: 'b, 'b, R: ?Sized + 'static>(
+        mut_: Self::Mut<'a, R>,
+    ) -> Self::Mut<'b, R> {
         Write::downcast_lifetime(mut_)
     }
 
@@ -312,12 +314,14 @@ impl<'a, T: ?Sized + 'static, S: AnyStorage> Write<'a, T, S> {
     }
 
     /// Downcast the lifetime of the mutable reference to the signal's value.
+    ///
+    /// This function enforces the variance of the lifetime parameter `'a` in Mut.  Rust will typically infer this cast with a concrete type, but it cannot with a generic type.
     pub fn downcast_lifetime<'b>(mut_: Self) -> Write<'b, T, S>
     where
         'a: 'b,
     {
         Write {
-            write: S::downcast_mut(mut_.write),
+            write: S::downcast_lifetime_mut(mut_.write),
             drop_signal: mut_.drop_signal,
         }
     }

packages/signals/src/write.rs

@@ -26,7 +26,9 @@ pub trait Writable: Readable {
     /// Downcast a mutable reference in a RefMut to a more specific lifetime
     ///
     /// This function enforces the variance of the lifetime parameter `'a` in Ref.
-    fn downcast_mut<'a: 'b, 'b, T: ?Sized + 'static>(mut_: Self::Mut<'a, T>) -> Self::Mut<'b, T>;
+    fn downcast_lifetime_mut<'a: 'b, 'b, T: ?Sized + 'static>(
+        mut_: Self::Mut<'a, T>,
+    ) -> Self::Mut<'b, T>;
 
     /// Get a mutable reference to the value. If the value has been dropped, this will panic.
     #[track_caller]
@@ -37,7 +39,7 @@ pub trait Writable: Readable {
     /// Try to get a mutable reference to the value.
     #[track_caller]
     fn try_write(&mut self) -> Result<WritableRef<'_, Self>, generational_box::BorrowMutError> {
-        self.try_write_unchecked().map(Self::downcast_mut)
+        self.try_write_unchecked().map(Self::downcast_lifetime_mut)
     }
 
     /// Try to get a mutable reference to the value without checking the lifetime.
@@ -238,7 +240,7 @@ impl<'a, T: 'static, R: Writable<Target = Vec<T>>> Iterator for WritableValueIte
             self.value.try_write_unchecked().unwrap(),
             |v: &mut Vec<T>| v.get_mut(index),
         )
-        .map(R::downcast_mut)
+        .map(R::downcast_lifetime_mut)
     }
 }