Update docs

docs/api/reactivity-core.md

@@ -2,6 +2,10 @@
 
 <br/>
 
+:::warning
+Yielding is not allowed in any reactive scope. Strict mode can check for this.
+:::
+
 ## root()
 
 Creates and runs a function in a new reactive scope.
@@ -14,18 +18,14 @@ Creates and runs a function in a new reactive scope.
 
 - **Details**
 
+    Returns the result of the given function.
+
     Creates a new root reactive scope, where creation and derivations of sources
     can be tracked and properly disposed of.
 
-    Returns the result of the given function.
-
     A function to destroy the root is passed into the callback, which will run
     any cleanups and allow derived sources created to garbage collect.
 
-    ::: warning
-    `fn()` cannot yield.
-    :::
-
 ## source()
 
 Creates a new source with the given value.
@@ -44,6 +44,8 @@ Creates a new source with the given value.
     Reading from the source from within a reactive scope will cause changes
     to that source to be tracked and anything depending on it to update.
 
+    Sources can be created outside of reactive scopes.
+
 - **Example**
 
     ```lua
@@ -56,7 +58,7 @@ Creates a new source with the given value.
 
 ## effect()
 
-Runs a side-effect on source update.
+Runs a side-effect in a new reactive scope on source update.
 
 - **Type**
 
@@ -66,14 +68,10 @@ Runs a side-effect on source update.
 
 - **Details**
 
-    The callback is ran immediately.
-
     Any time a source referenced in the callback is changed, the callback will
     be reran.
 
-    ::: warning
+    The callback is ran to initially ran on first call to find dependent sources.
-    `callback()` cannot yield.
-    :::
 
 - **Example**
 
@@ -93,7 +91,7 @@ Runs a side-effect on source update.
 
 ## derive()
 
-Derives a new source from existing sources.
+Derives a new source in a new reactive scope from existing sources.
 
 - **Type**
 
@@ -109,12 +107,7 @@ Derives a new source from existing sources.
     Anytime its value is recalculated it is also cached, subsequent calls will
     retun this cached value until it recalculates again.
 
-    Takes a callback that is immediately run to determine what sources are being
+    The callback is ran to initially ran on first call to find dependent sources.
-    referenced.
-
-    ::: warning
-    `source()` cannot yield.
-    :::
 
 - **Example**
 

docs/api/reactivity-utility.md

@@ -2,7 +2,7 @@
 
 ## cleanup()
 
-Runs a callback anytime a reactive scope is re-ran.
+Runs a callback anytime a reactive scope is reran or destroyed.
 
 - **Type**
 
@@ -26,7 +26,8 @@ Runs a callback anytime a reactive scope is re-ran.
 
 ## untrack()
 
-Runs a given function where any sources read will not track its reactive scope.
+Runs a given function where any sources read will not be tracked by a reactive
+scope.
 
 - **Type**
 
@@ -58,7 +59,8 @@ Runs a given function where any sources read will not track its reactive scope.
 
 ## read()
 
-Utility used to read a value that is either a primitive or a source.
+Utility used to read a value that is either a primitive or a source. Sources
+read can still be tracked inside a reactive-scope.
 
 - **Type**
 

docs/tut/crash-course/5-effect.md

@@ -1,7 +1,7 @@
 # Effect
 
 Effects are functions that are ran in response to source updates. They are
-alled effects because they cause *side-effects* when reacting to source updates.
+called effects because they cause *side-effects* when reacting to source updates.
 
 Effects are created using `effect()`.
 

docs/tut/crash-course/6-stateful-component.md

@@ -23,7 +23,7 @@ local function Counter()
         instance.Text = "count: " .. count()
     end)
 
-    return count
+    return instance
 end
 ```
 
@@ -49,7 +49,7 @@ local function Counter(props: { count: () -> number })
         instance.Text = "count: " .. count()
     end)
 
-    return count
+    return instance
 end
 
 local count = source(0)