Start writing some language and tooling documentation.

Part of #12.

Author: alexrp

doc/language/syntactic-structure/expressions/control/break.md

@@ -4,3 +4,21 @@
 break-expression ::= 'break' break-expression-result?
 break-expression-result ::= 'as' expression
 ```
+
+Stops the evaluation of the enclosing [`while` expression](while.md) or
+[`for` expression](for.md). In other words, a `break` expression is semantically
+equivalent to transferring control to just after the final statement of the
+*loop body*, and then performing no further iterations. If a
+`break-expression-result` is present, the [`expression`](../../expressions.md)
+(the *result*) becomes the result of the enclosing `while` expression or `for`
+expression.
+
+Any [`defer` statements](../../statements/defer.md) that would go out of scope
+due to the control transfer are executed before stopping the loop.
+
+It is a semantic error for a `break` expression to appear outside of the *loop
+body* of a `while` expression or `for` expression. If a `break` expression
+appears in the *body* of a `defer` statement, it cannot bind to a `while`
+expression or `for` expression outside of the *body*.
+
+A `break` expression has no result value.

doc/language/syntactic-structure/expressions/control/condition.md

@@ -4,3 +4,13 @@
 condition-expression ::= 'cond' '{' condition-expression-arm (',' condition-expression-arm)* ','? '}'
 condition-expression-arm ::= expression '->' expression
 ```
+
+For each `condition-expression-arm`, in lexical order, evaluates the first
+[`expression`](../../expressions.md) (the *condition*). The first *condition*
+that tests as [truthy](if.md#truthiness) causes the associated second
+`expression` (the *body*) to be evaluated and the evaluation of arms to stop. If
+no *body* is evaluated during this process, a panic occurs.
+
+<!-- TODO: Link to panic definition. -->
+
+The whole expression results in the value of the evaluated *body*.

doc/language/syntactic-structure/expressions/control/if.md

@@ -4,3 +4,25 @@
 if-expression ::= 'if' expression block-expression if-expression-else?
 if-expression-else ::= 'else' block-expression
 ```
+
+Evaluates the [`expression`](../../expressions.md) (the *condition*). If the
+result tests as [truthy](#truthiness), the first
+[`block-expression`](../block.md) (the *then body*) is evaluated. Otherwise, if
+an `if-expression-else` clause is present, the second `block-expression` (the
+*else body*) is evaluated.
+
+The whole expression results in one of the following values, in order:
+
+1. The result of the *then body*.
+2. The result of the *else body*, if an `if-expression-else` is present.
+3. The [nil value](../../../lexical-structure/literals.md#nil-literal).
+
+## Truthiness
+
+<!-- TODO: Move this section elsewhere? -->
+
+Almost all values are considered truthy, with the following exceptions:
+
+* The [nil value](../../../lexical-structure/literals.md#nil-literal).
+* The
+  [`false` Boolean value](../../../lexical-structure/literals.md#boolean-literal).

doc/language/syntactic-structure/expressions/control/next.md

@@ -3,3 +3,19 @@
 ```ebnf
 next-expression ::= 'next'
 ```
+
+Skips the remaining portion of the *loop body* of the enclosing
+[`while` expression](while.md) or [`for` expression](for.md) and starts a new
+iteration. In other words, a `next` expression is semantically equivalent to
+transferring control to just after the final statement of the *loop body*.
+
+Any [`defer` statements](../../statements/defer.md) that would go out of scope
+due to the control transfer are executed before the next loop iteration is
+started.
+
+It is a semantic error for a `next` expression to appear outside of the *loop
+body* of a `while` expression or `for` expression. If a `next` expression
+appears in the *body* of a `defer` statement, it cannot bind to a `while`
+expression or `for` expression outside of the *body*.
+
+A `next` expression has no result value.

doc/language/syntactic-structure/expressions/control/return.md

@@ -3,3 +3,20 @@
 ```ebnf
 return-expression ::= 'tail'? 'ret' expression
 ```
+
+Evaluates [`expression`](../../expressions.md) (the *result*), explicitly
+returns *result* from the current
+[`fn` declaration](../../declarations/function.md) or
+[lambda expression](../values/lambda.md), and transfers control to the caller.
+
+Any [`defer` statements](../../statements/defer.md) that would go out of scope
+due to the control transfer are executed after evaluating *result*, but before
+returning it to the caller.
+
+It is a semantic error for a `ret` expression to appear outside of an `fn`
+declaration or lambda expression. A `ret` expression cannot appear in the *body*
+of a `defer` statement, unless it is nested in a lambda expression.
+
+A `ret` expression has no result value.
+
+<!-- TODO: Document tail calls. -->

doc/language/syntactic-structure/expressions/control/while.md

@@ -4,3 +4,17 @@
 while-expression ::= 'while' expression block-expression while-expression-else?
 while-expression-else ::= 'else' block-expression
 ```
+
+Evaluates the first [`block-expression`](../block.md) (the *loop body*)
+repeatedly until the [`expression`](../../expressions.md) (the *condition*) no
+longer tests as [truthy](if.md#truthiness). The *condition* is evaluated at the
+beginning of every iteration. If no iterations run and a
+`while-expression-else` is present, the second `block-expression` (the *else
+body*) is evaluated once.
+
+The whole expression results in one of the following values, in order:
+
+1. The result of any [`break as` expression](break.md) within the *loop body*.
+2. The result of the *loop body*, if at least one iteration completes.
+3. The result of the *else body*, if a `while-expression-else` is present.
+4. The [nil value](../../../lexical-structure/literals.md#nil-literal).

doc/language/syntactic-structure/statements/assert.md

@@ -3,3 +3,16 @@
 ```ebnf
 assert-statement ::= 'assert' expression
 ```
+
+Evaluates [`expression`](../expressions.md) (the *condition*). If the result
+does not test as [truthy](../expressions/control/if.md#truthiness), a panic
+occurs. An `assert` statement is always executed; it is not conditional on build
+flags or similar.
+
+<!-- TODO: Link to panic definition. -->
+
+An `assert` statement is typically used in a
+[`test` declaration](../declarations/test.md) to verify the outcome of a unit
+test, but it can also be used in regular code. The runtime system is allowed to
+optimize with the assumption that *condition* holds after the `assert`
+statement.

doc/language/syntactic-structure/statements/defer.md

@@ -3,3 +3,10 @@
 ```ebnf
 defer-statement ::= 'defer' expression
 ```
+
+Defers evaluation of [`expression`](../expressions.md) (the *body*) until
+control leaves the enclosing [block expression](../expressions/block.md).
+Multiple `defer` statements are evaluated in reverse lexical order.
+
+`defer` statements are typically used to reliably clean up resources regardless
+of how control leaves a block expression.

doc/language/syntactic-structure/statements/expression.md

@@ -3,3 +3,8 @@
 ```ebnf
 expression-statement ::= expression
 ```
+
+Evaluates [`expression`](../expressions.md) (the *result*). If the expression
+statement is the final statement of the enclosing
+[block expression](../expressions/block.md), *result* becomes the result of the
+block expression.

doc/language/syntactic-structure/statements/let.md

@@ -3,3 +3,13 @@
 ```ebnf
 let-statement ::= 'let' pattern '=' expression
 ```
+
+Evaluates [`expression`](../expressions.md) (the *initializer*) and matches it
+against [`pattern`](../patterns.md). If the match fails, a panic occurs.
+
+<!-- TODO: Link to panic definition. -->
+
+Any [bindings](../patterns.md#pattern-bindings) in `pattern` are available for
+the remainder of the enclosing [block expression](../expressions/block.md). Any
+in `pattern` that existed prior to the `let` statement are shadowed for the
+remainder of the enclosing block expression.