doc/ref/spec.md: document error builtin

Issue #291
Issue #943

Signed-off-by: Marcel van Lohuizen <[email protected]>
Change-Id: I8121ab402d97902c86fee1aaa31d1c0a5d036541
Dispatch-Trailer: {"type":"trybot","CL":1217233,"patchset":3,"ref":"refs/changes/33/1217233/3","targetBranch":"master"}

Author: mpvl

doc/ref/spec.md

@@ -2671,6 +2671,21 @@ b: "Hello \( a )!" // Hello World!
 
 Builtin functions are predeclared. They are called like any other function.
 
+### `error`
+
+`error` allows user to create an error value with a custom message.
+An error value can be used in a disjunction, where it will be discarded if
+there is a valid disjunct, but it will be reported as the sole error value in
+case all disjuncts fail.
+
+`error` takes a single string argument. If this argument is a literal
+interpolation, it will be extra resilient: if any of the arguments to the
+interpolation fail, they will be printed as an expression. This allows failing
+expressions to be a part of the error message.
+
+```
+a: 1/0 | error("infinity and beyond!: \(1/0)")
+```
 
 ### `len`