Update docs

docs/api/reactivity-utility.md

@@ -1,16 +1,15 @@
-# Reactivity API: Utility
+# Reactivity: Utility
 
 ## cleanup()
 
-Runs a callback anytime a scope is reran or destroyed.
+Queues a callback to run when a scope is reran or destroyed.
 
 - **Type**
 
     ```luau
-    function cleanup(callback: () -> ())
-    function cleanup(obj: Destroyable)
-    function cleanup(obj: Disconnectable)
+    function cleanup(v: Function | Disconnectable | Destroyable)
 
+    type Function = () -> ()
     type Destroyable = { destroy: () -> () }
     type Disconnectable = { disconnect: () -> () }
     ```
@@ -18,20 +17,27 @@ Runs a callback anytime a scope is reran or destroyed.
 - **Example**
 
     ```luau
-    local data = source(1)
+    local count = source(0)
 
-    effect(function()
-        local label = create "TextLabel" { Text = data() }
+    local destroy = root(function()
+        effect(function()
+            count()
 
-        cleanup(function()
-            label:Destroy()
+            cleanup(function()
+                print "cleaned"
+            end)
         end)
-    end)
+    end
+
+    -- nothing printed yet
+    count(1) -- prints "cleaned"
+    count(2) -- prints "cleaned"
+    destroy() -- prints "cleaned"
     ```
 
-## untrack()
+## untrack() <Badge type="info" text="STABLE"><a href="/vide/api/reactivity-core#Scopes">STABLE</a></Badge>
 
-Runs a given function in a new stable scope.
+Runs a function in a new stable scope.
 
 - **Type**
 
@@ -55,16 +61,15 @@ Runs a given function in a new stable scope.
     end)
 
     print(sum()) -- 0
-    b(1)
+    b(1) -- untracked so reactive scope created by derive() does not rerun
     print(sum()) -- 0
-    a(1)
+    a(1) -- reactive scope created by derive() reruns
     print(sum()) -- 2
     ```
 
 ## read()
 
-Utility used to read a value that is either a primitive or a source. Sources
-read can still be tracked inside a reactive scope.
+Utility used to read a value that is either a primitive or a source.
 
 - **Type**
 
@@ -74,8 +79,8 @@ read can still be tracked inside a reactive scope.
 
 ## batch()
 
-Runs a given function where any source updates made within the function do not
-trigger effects until after the function finishes running.
+Runs a function where any source updates made within the function do not
+trigger effects until after the function ends.
 
 - **Type**
 
@@ -86,11 +91,29 @@ trigger effects until after the function finishes running.
 - **Details**
 
     Improves performance when an effect depends on multiple sources, and those
-    sources need to be updated. Updating those sources inside a batch call will
-    only cause the effect to run once after the batch call ends instead of after
-    each time a source is updated.
+    sources need to be updated.
 
-## context()
+- **Example**
+
+    ```luau
+    local a = source(0)
+    local b = source(0)
+
+    effect(function()
+        print(a() + b())
+    end)
+
+    -- prints "0"
+
+    batch(function()
+        a(1) -- no print
+        b(2) -- no print
+    end)
+
+    -- prints "3"
+    ```
+
+## context() <Badge type="info" text="STABLE"><a href="/vide/api/reactivity-core#Scopes">STABLE</a></Badge>
 
 Creates a new context.
 
@@ -101,15 +124,17 @@ Creates a new context.
 
     type Context<T> =
         () -> T -- get
-        & (T, () -> ()) -> () -- set
+        & <U>(T, () -> U) -> U -- set
     ```
 
 - **Details**
 
     Calling `context()` returns a new context function.
     Call this function with no arguments to get the context value.
-    Call this function with a value and a callback to set a new context with the
-    given value.
+    Call this function with a value and a function to create a new context with
+    the given value.
+
+    The new context is run under a stable scope.
 
 - **Example**
 
@@ -131,4 +156,3 @@ Creates a new context.
     end)
     ```
 
---------------------------------------------------------------------------------