docs: complete MODULES.md. minor updates elsewhere. prepare for hosting

1 files changed, 18 insertions, 24 deletions

diff --git a/docs/ERRORS.md b/docs/ERRORS.md
index 4f99e7c..33c15d5 100644
--- a/docs/ERRORS.md
+++ b/docs/ERRORS.md
@@ -1,23 +1,6 @@
 # Error Handling
 
-Puck's error handling is shamelessly stolen from Swift.
-It uses a combination of Option/Result types and try/catch/finally statements, and leans somewhat on Puck's metaprogramming capabilities.
-
-```puck
-func get_debug[T](): T =
-  let value: Option[T] = self.unsafe_get(413)
-  try:
-    let value = value!
-  catch Exception(e)
-
-
-try:
-  ..
-catch:
-  ..
-finally:
-  print "No such errors"
-```
+Puck's error handling is shamelessly stolen from Swift. It uses a combination of `Option`/`Result` types and `try`/`catch` statements, and leans somewhat on Puck's metaprogramming capabilities.
 
 There are several ways to handle errors in Puck. If the error is encoded in the type, one can:
 1. `match` on the error
@@ -25,10 +8,9 @@ There are several ways to handle errors in Puck. If the error is encoded in the
 3. propagate the error with `?`
 4. throw the error with `!`
 
-If an error is thrown, one must explicitly handle (or disregard) it with a `try/catch` block.
-This method of error handling may feel more familiar to Java programmers.
+If an error is thrown, one **must** explicitly handle (or disregard) it with a `try/catch` block or risk runtime failure. This method of error handling may feel more familiar to Java programmers.
 
-## Errors as monads
+## Errors as Monads
 
 Puck provides [`Option[T]`](std/default/options.pk) and a [`Result[T, E]`](std/default/results.pk) types, imported by default. These are `union` types and so must be pattern matched upon to be useful: but the standard library provides [a bevy of helper functions](std/default/results.pk).
 Two in particular are of note. The `?` operator unwraps a Result or propagates its error up a function call (and may only be used in type-appropriate contexts). The `!` operator unwraps an Option or Result directly or throws an exception in the case of None or Error.
@@ -56,12 +38,12 @@ The utility of the provided helpers in [`std.options`](std/default/options.pk) a
 
 A notable helpful type is the aliasing of `Result[T]` to `Result[T, ref Err]`, for when the particular error does not matter. This breaks `try`/`catch` exhaustion (as `ref Err` denotes a reference to *any* Error), but is particularly useful when used in conjunction with the propagation operator.
 
-## Errors as catchable exceptions
+## Errors as Catchable Exceptions
 
 Errors raised by `raise`/`throw` (or subsequently the `!` operator) must be explicitly caught and handled via a `try`/`catch`/`finally` statement.
 If an exception is not handled within a function body, the function must be explicitly marked as a throwing function via the `yeet` prefix (name to be determined). The compiler will statically determine which exceptions in particular are thrown from any given function, and enforce them to be explicitly handled or explicitly ignored.
 
-Errors are types. An error thrown from an unwrapped `Result[T, E]` is of type `E`. `catch` statements, then, may pattern match upon possible errors, behaving similarly to `of` branches.
+Despite functioning here as exceptions: errors remain types. An error thrown from an unwrapped `Result[T, E]` is of type `E`. `catch` statements, then, may pattern match upon possible errors, behaving similarly to `of` branches.
 
 ```puck
 try:
@@ -76,7 +58,19 @@ This creates a distinction between two types of error handling, working in sync:
 
 <!-- [nullable types](https://en.wikipedia.org/wiki/Nullable_type)?? -->
 
-## Unrecoverable exceptions
+## Errors and Void Functions
+
+Some functions do not return a value but can still fail: for example, setters.
+This can make it difficult to do monadic error handling elegantly: one could return a `Result[void, E]`, but...
+
+```puck
+pub func set[T](self: list[T], i: uint, val: T) =
+  if i > self.length:
+    raise IndexOutOfBounds
+  self.data.raw_set(offset = i, val)
+```
+
+## Unrecoverable Exceptions
 
 There exist errors from which a program can not reasonably recover. These are the following:
 - `Assertation Failure`: a call to an `assert` function has returned false at runtime.