Update docs

4 files changed, 135 insertions, 4 deletions

diff --git a/api/arrays.md b/api/arrays.md
index 8933ff1e..34da6e8f 100644
--- a/api/arrays.md
+++ b/api/arrays.md
@@ -21,6 +21,8 @@ like this:
 empty := [:Int]
 ```
 
+For type annotations, an array that holds items with type `T` is written as `[T]`.
+
 ### Array Comprehensions
 
 Arrays can also use comprehensions, where you specify how to dynamically create
@@ -76,6 +78,9 @@ You can iterate over the items in an array like this:
 ```tomo
 for item in array:
     ...
+
+for i, item in array:
+    ...
 ```
 
 Array iteration operates over the value of the array when the loop began, so
diff --git a/api/channels.md b/api/channels.md
index 880825ce..4b8d416a 100644
--- a/api/channels.md
+++ b/api/channels.md
@@ -3,6 +3,13 @@
 Channels are a thread-safe message queue for communicating between threads,
 although they can also be used as a general-purpose queue.
 
+## Syntax
+
+The syntax to create a channel is `|T|`, where `T` is the type that will be
+passed through the channel. You can also specify a maximum size for the
+channel, which will cause pushing to block until the recipient has popped from
+the channel if the maximum size is reached.
+
 ```tomo
 channel := |Int|
 channel:push(10)
@@ -11,6 +18,8 @@ channel:push(20)
 = 10
 >> channel:pop()
 = 20
+
+small_channel := |Int; max_size=5|
 ```
 
 ## Channel Methods
diff --git a/api/sets.md b/api/sets.md
index 7bcd4805..6dcc9ca9 100644
--- a/api/sets.md
+++ b/api/sets.md
@@ -10,11 +10,61 @@ b := {20, 30}
 = {20}
 ```
 
-Here’s the Markdown documentation for set functions:
+## Syntax
 
----
+Sets are written using `{}` curly braces with comma-separated items:
+
+```tomo
+nums := {10, 20, 30}
+```
+
+Empty sets must specify the item type explicitly:
+
+```tomo
+empty := {:Int}
+```
+
+For type annotations, a set that holds items with type `T` is written as `{T}`.
+
+### Comprehensions
+
+Similar to arrays, sets can use comprehensions:
+
+```tomo
+set := {10*i for i in 10}
+set2 := {10*i for i in 10 if i mod 2 == 0}
+set3 := {-10, 10*i for i in 10}
+```
+
+## Accessing Items
+
+Sets internally store their items in an array, which you can access with the
+`.items` field. This is a constant-time operation that produces an immutable
+view:
+
+```tomo
+set := {10, 20, 30}
+>> set.items
+= [10, 20, 30]
+```
+
+## Iteration
+
+You can iterate over the items in a table like this:
+
+```tomo
+for item in set:
+    ...
+
+for i, item in set:
+    ...
+```
+
+Set iteration operates over the value of the set when the loop began, so
+modifying the set during iteration is safe and will not result in the loop
+iterating over any of the new values.
 
-## Set Functions
+## Set Methods
 
 ### `has`
 
diff --git a/api/tables.md b/api/tables.md
index bdf1ef15..f132d70a 100644
--- a/api/tables.md
+++ b/api/tables.md
@@ -10,7 +10,74 @@ the methods `:get(key)` and `:set(key, value)`. This is explicit to avoid
 hiding the fact that table lookups and table insertion are performing function
 calls and have edge conditions like a failure to find an entry.
 
----
+## Syntax
+
+Tables are written using `{}` curly braces with `:` colons associating key
+expressions with value expressions and commas between entries:
+
+```tomo
+table := {"A": 10, "B": 20}
+```
+
+Empty tables must specify the key and value types explicitly:
+
+```tomo
+empty := {:Text:Int}
+```
+
+For type annotations, a table that maps keys with type `K` to values of type
+`V` is written as `{K:V}`.
+
+### Comprehensions
+
+Similar to arrays, tables can use comprehensions to dynamically construct tables:
+
+```tomo
+t := {i: 10*i for i in 10}
+t := {i: 10*i for i in 10 if i mod 2 == 0}
+t := {-1:-10, i: 10*i for i in 10}
+```
+
+### Fallback Tables
+
+Tables can specify a fallback table that is used when looking up a value if it
+is not found in the table itself:
+
+```tomo
+t := {"A": 10}
+t2 := {"B": 20; fallback=t}
+>> t2:get("A")
+= 10
+```
+
+## Accessing Keys and Values
+
+The keys and values of a table can be efficiently accessed as arrays using a
+constant-time immutable slice of the internal data from the table:
+
+```tomo
+t := {"A": 10, "B": 20}
+>> t.keys
+= ["A", "B"]
+>> t.values
+= [10, 20]
+```
+
+## Iteration
+
+You can iterate over the key/value pairs in a table like this:
+
+```tomo
+for key, value in table:
+    ...
+
+for key in table:
+    ...
+```
+
+Table iteration operates over the value of the table when the loop began, so
+modifying the table during iteration is safe and will not result in the loop
+iterating over any of the new values.
 
 ## Table Methods