From 3c0bf948ac17ab389e8cdf683a00022aa8f10561 Mon Sep 17 00:00:00 2001
From: Jesse Brault <jbrault@mac.com>
Date: Thu, 12 Mar 2026 15:17:34 -0500
Subject: [PATCH] Start writing documentation on compiler errors.

---
 doc/deimos.asciidoc.adoc | 81 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 doc/deimos.asciidoc.adoc

diff --git a/doc/deimos.asciidoc.adoc b/doc/deimos.asciidoc.adoc
new file mode 100644
index 0000000..fa9ffc1
--- /dev/null
+++ b/doc/deimos.asciidoc.adoc
@@ -0,0 +1,81 @@
+= Deimos
+Jesse Brault <jesse@jessebrault.com>
+0.1.0
+:toc:
+
+== Compile Error Explanations
+
+=== Not more than one constructor
+
+Classes may have up to only one constructor. The following does not compile:
+
+[source]
+----
+class Foo
+    ctor(bar: Int) end
+    ctor(baz: String) end // Error
+end
+----
+
+=== Field must be initialized
+
+All class fields must be initialized in their declaration, or in the constructor. It
+is an error to leave a field uninitialized.
+
+[source]
+----
+class Foo
+    bar: Int // Error: no initializer
+end
+
+class Bar
+    baz: Int // Error: no initializer
+
+    ctor()
+        // some other stuff
+    end
+end
+----
+
+=== Use of field before initialization
+
+A field _without_ a declared initializer (i.e., one present at its declaration, not the constructor) may not be read in
+the initializer of any other field or constructor variable, as the language does not guarantee a specific ordering of
+field initialization and cannot statically analyze field/variable dependencies.
+
+[source]
+----
+class Foo
+    bar: Int
+    baz = bar // Error
+end
+
+class Bar
+    foo: Int
+    baz = fnWithArg(foo) // Error
+end
+
+class Baz
+    foo: Int
+    qux: String
+
+    ctor(baz: String)
+        qux = foo + baz // Error: attempt to read uninitialized foo
+    end
+end
+----
+
+The exception to this is reading the field inside another field's initializer *only* when that expression is itself a
+closure.
+
+[source]
+----
+class Foo
+    bar: Int
+    baz = { bar } // OK
+
+    ctor(bar: Int)
+        self.bar = bar
+    end
+end
+----
\ No newline at end of file