From 4b877ce8ff3e8b09529c9b0d231009ef7afe2eb1 Mon Sep 17 00:00:00 2001
From: Aaron Smith <83140718+centau@users.noreply.github.com>
Date: Thu, 21 Sep 2023 10:29:14 +0100
Subject: [PATCH] Update docs

---
 docs/api/reactivity-core.md                   | 31 +++++++------------
 docs/api/reactivity-utility.md                |  8 +++--
 docs/tut/crash-course/5-effect.md             |  2 +-
 docs/tut/crash-course/6-stateful-component.md |  4 +--
 4 files changed, 20 insertions(+), 25 deletions(-)

diff --git a/docs/api/reactivity-core.md b/docs/api/reactivity-core.md
index 0e4a5d0..133bc4a 100644
--- a/docs/api/reactivity-core.md
+++ b/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
-    `callback()` cannot yield.
-    :::
+    The callback is ran to initially ran on first call to find dependent sources.
 
 - **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
-    referenced.
-
-    ::: warning
-    `source()` cannot yield.
-    :::
+    The callback is ran to initially ran on first call to find dependent sources.
 
 - **Example**
 
diff --git a/docs/api/reactivity-utility.md b/docs/api/reactivity-utility.md
index 9219b29..d5292e5 100644
--- a/docs/api/reactivity-utility.md
+++ b/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**
 
diff --git a/docs/tut/crash-course/5-effect.md b/docs/tut/crash-course/5-effect.md
index 3891652..c875de9 100644
--- a/docs/tut/crash-course/5-effect.md
+++ b/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()`.
 
diff --git a/docs/tut/crash-course/6-stateful-component.md b/docs/tut/crash-course/6-stateful-component.md
index ba167e2..ce9d8d6 100644
--- a/docs/tut/crash-course/6-stateful-component.md
+++ b/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)