d o c

doc/src/05_building_block_view.adoc

@@ -2,18 +2,19 @@
 
 [[section-building-block-view]]
 
-
 == Building Block View
 
 ==== Parser `parser.rs`
 
-Lexes the source code, and then parses those tokens into an abstract syntax tree.
+Tokenizes the source code, and then parses those tokens into an abstract syntax tree.
 
 [source,rust]
 ----
-include::{sourcedir}/parser.rs[tag=parse]
+include::{sourcedir}/parser.rs[tag=stmt]
 ----
 
+The AST accepts arbitrary expressions as arguments to instructions. This allows it to generate better diagnostics later.
+
 
 ==== Compiler and IR `ir.rs`
 

doc/src/06_runtime_view.adoc

@@ -16,16 +16,3 @@ The interpreter follows a classic interpreter architecture. First, the source is
 Then, a handwritten recursive descent parser parses the token stream. The abstract syntax tree is then given to a small compiler, that compiles it down to a smaller and more limited IR. It also resolves jump labels to offsets.
 
 The interpreter then executes this lower level IR.
-
-
-=== <Runtime Scenario 1>
-
-* _<insert runtime diagram or textual description of the scenario>_
-* _<insert description of the notable aspects of the interactions between the
-building block instances depicted in this diagram.>_
-
-=== <Runtime Scenario 2>
-
-=== ...
-
-=== <Runtime Scenario n>

doc/src/08_concepts.adoc

@@ -1,22 +1,23 @@
+:sourcedir: ../../src
+
 [[section-concepts]]
 == Cross-cutting Concepts
 
+=== Version control
 
+This project uses git and Github for version control.
 
+=== Error handling
 
+A single type is used for handling invalid input. The error has a single message, a span that shows the location in the source code, and optionally some notes or a help message. This message is then printed using the `ariadne` crate.
 
-=== _<Concept 1>_
+[source,rust]
+----
+include::{sourcedir}/error.rs[tag=error]
+----
 
-_<explanation>_
+If the interpreter enters an invalid state, it panics.
 
+=== Unsafe code
 
-
-=== _<Concept 2>_
-
-_<explanation>_
-
-...
-
-=== _<Concept n>_
-
-_<explanation>_
+Currently, `#![forbid(unsafe_code)]` is used in the crate, but unsafe code may be used for performance improvements in the future.

doc/src/09_architecture_decisions.adoc

@@ -15,4 +15,8 @@ It would be simpler to simply walk over the AST during interpretation, but this
 
 * There would still have to be a second pass over the AST to resolve labels.
 
-Therefore, an IR is used to resolve the labels and interpret it.
+Therefore, an IR is used to resolve the labels and interpret it.
+
+=== Depend on `logos` for the lexer
+
+Don't write a lexer by hand, let `logos` generate it. This saves development time and makes it easier to add new features to the lexer.

doc/src/10_quality_requirements.adoc

@@ -1,13 +1,29 @@
 [[section-quality-scenarios]]
 == Quality Requirements
 
-
-
+* Parser tests
+* Idiomatic Rust code
+* Good diagnostics
 
 === Quality Tree
 
+[plantuml]
+----
+left to right direction
+(Quality) --> (maintainability)
+(maintainability) --> (1 parser tests)
+(maintainability) --> (2 idiomatic rust code)
 
+(Quality) --> (usability)
+(usability) --> (3 diagnostics)
+----
 
 === Quality Scenarios
 
-
+[cols="e,4e" options="header"]
+|===
+|ID|Scenario
+|1|A developer wants to add a new feature to the parser. It should be ensured that they don't break existing functionality.
+|2|A new developer that is already familiar with rust wants to get started contributing to the project. The project should be familiar to them.
+|3|Someone wants to use crapderive, but they have syntax errors since they aren't familiar with the language yet. The compiler should help them find the issues and fix them.
+|===

doc/src/config.adoc

@@ -7,3 +7,5 @@
 
 // where are images located?
 :imagesdir: ./images
+
+:sourcedir: ../../src