Add basic info about parser design to docs
@@ -71,9 +71,28 @@ Pay attention especially to the following sections:
- **Architecture Invariant**: important note about crucial assumptions about the code/behavior
- **API Boundary**: an exposed interface that requires careful design, e.g. because it has internal users to support
+### `ast`
+
+Types that serve as the Gleam AST, both in its *untyped* and *typed* form.
+Each tree describes a single Gleam module at its root.
+
+Untyped trees contain untyped expressions only.
+
+Typed trees contain typed expressions together with metadata
+such as the types of expressions and information on how to generate code for each value constructor used.
+Here, code has gained the context necessary to produce final Gleam output.
+
### `parse`
-TODO
+The parser receives source code for a single Gleam module (as `&str`, as opposed to a stream)
+and produces an untyped AST together with `ModuleExtra`
+containing various types of comments plus empty lines.
+
+Currently this means that parsing is tightly coupled with the AST structure.
+
+**Architecture Invariant**: parsing may fail, the output is in `Result<T, Error>` form.
+
+**API Boundary**: high-level operations on code, such as formatting, begin here.
### `erl`
