From 1d56ed5daca284b47c8b9de530ddbdf81c9f996c Mon Sep 17 00:00:00 2001
From: nils <48135649+Nilstrieb@users.noreply.github.com>
Date: Mon, 4 Jul 2022 08:38:14 +0200
Subject: [PATCH] doc doc

---
 doc/src/05_building_block_view.adoc    | 37 ++++++++------------------
 doc/src/09_architecture_decisions.adoc | 13 +++++++++
 doc/src/11_technical_risks.adoc        |  2 --
 src/ir.rs                              |  2 ++
 4 files changed, 26 insertions(+), 28 deletions(-)

diff --git a/doc/src/05_building_block_view.adoc b/doc/src/05_building_block_view.adoc
index 7bd09a0..ff58f48 100644
--- a/doc/src/05_building_block_view.adoc
+++ b/doc/src/05_building_block_view.adoc
@@ -14,49 +14,34 @@
 [Interpreter] <--> () IO : stdin and stdout
 ----
 
-Motivation::
-
 The interpreter follows a classic interpreter architecture. First, the source is tokenized by a lexer, implemented using the `logos` library (https://crates.io/crates/logos).
 
-The, 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.
+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.
 
-==== Parser
+==== Parser `parser.rs`
 
-Lexes the source code, and then turns those tokens into an abstract syntax tree.
+Lexes the source code, and then parses those tokens into an abstract syntax tree.
 
 [source,rust]
 ----
 include::{sourcedir}/parser.rs[tag=parse]
 ----
 
-_<(Optional) Quality/Performance Characteristics>_
 
-_<(Optional) Directory/File Location>_
+==== Compiler and IR `ir.rs`
 
-_<(Optional) Fulfilled Requirements>_
+[source,rust]
+----
+include::{sourcedir}/ir.rs[tag=stmt]
+----
 
-_<(optional) Open Issues/Problems/Risks>_
+The compiler compiles the AST into the IR, resolving labels.
 
+==== Interpreter `interpret.rs`
 
-
-
-==== <Name black box 2>
-
-_<black box template>_
-
-==== <Name black box n>
-
-_<black box template>_
-
-
-==== <Name interface 1>
-
-...
-
-==== <Name interface m>
-
+The interpreter interprets the IR and interacts with the outside world through standard input and output.
 
 
 === Level 2
diff --git a/doc/src/09_architecture_decisions.adoc b/doc/src/09_architecture_decisions.adoc
index d40ca52..be77748 100644
--- a/doc/src/09_architecture_decisions.adoc
+++ b/doc/src/09_architecture_decisions.adoc
@@ -1,5 +1,18 @@
 [[section-design-decisions]]
 == Architecture Decisions
 
+=== Use a single binary crate
 
+Since the project is small and self-contained, using a single binary crate is enough. In the future, it could still be migrated to using a binary+library crate.
 
+=== Use an IR
+
+It would be simpler to simply walk over the AST during interpretation, but this presents several problems:
+
+* The AST is more permissive than the language, therefore it would have to be checked at runtime.
+
+* The AST is not optimized for interpretation efficiency, because it's not cache efficient.
+
+* 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.
\ No newline at end of file
diff --git a/doc/src/11_technical_risks.adoc b/doc/src/11_technical_risks.adoc
index 9680417..1e0bfcc 100644
--- a/doc/src/11_technical_risks.adoc
+++ b/doc/src/11_technical_risks.adoc
@@ -1,5 +1,3 @@
 [[section-technical-risks]]
 == Risks and Technical Debts
 
-
-
diff --git a/src/ir.rs b/src/ir.rs
index 41420fb..fee4e62 100644
--- a/src/ir.rs
+++ b/src/ir.rs
@@ -33,6 +33,7 @@ pub struct Location {
 }
 
 #[derive(Debug, Clone, Copy, DebugPls)]
+// tag::stmt[]
 pub enum Stmt {
     Mov { to: Place, from: Value },
     Movb { to: Place, from: Value },
@@ -45,6 +46,7 @@ pub enum Stmt {
     Je { to: Location },
     Cmp { lhs: Value, rhs: Value },
 }
+// end::stmt[]
 
 struct CompileCtx {
     stmts: Vec<Stmt>,