From 5b0d5c931fe8bd2d39c08b9cb684d6435e263b83 Mon Sep 17 00:00:00 2001
From: Eduard Urbach <admin@akyoto.dev>
Date: Sat, 28 Oct 2023 12:51:19 +0200
Subject: [PATCH] Improved documentation

---
 README.md | 42 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 37 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9cbc7db..7591367 100644
--- a/README.md
+++ b/README.md
@@ -24,12 +24,44 @@ Build a Linux ELF executable from `examples/hello`:
 ./examples/hello/hello
 ```
 
-## Source
+## Documentation
 
-- [main.go](main.go)
-- [src/cli/Main.go](src/cli/Main.go)
-- [src/cli/Build.go](src/cli/Build.go)
-- [src/build/Build.go](src/build/Build.go)
+### [main.go](main.go)
+
+Entry point. It simply calls `cli.Main()` which we can use for testing.
+
+### [src/cli/Main.go](src/cli/Main.go)
+
+The command line interface expects a command like `build` as the first argument.
+Commands are implemented as functions in the [src/cli](src/cli) directory.
+Each command has its own set of parameters.
+
+### [src/cli/Build.go](src/cli/Build.go)
+
+The build command creates a new `Build` instance with the given directory and calls the `Run` method.
+
+If no directory is specified, it will use the current directory.
+
+If the `--dry` flag is specified, it will perform all tasks except the final write to disk.
+This flag should be used in most tests and benchmarks to avoid needless disk writes.
+
+```shell
+q build
+q build examples/hello
+q build examples/hello --dry
+```
+
+### [src/build/Build.go](src/build/Build.go)
+
+The `Build` type defines all the information needed to start building an executable file.
+The name of the executable will be equal to the name of the build directory.
+
+`Run` starts the build which will scan all files in the build directory.
+The functions found in the scan will be translated to generic assembler instructions.
+All the functions that are required to run the program will be added to final assembler.
+The final assembler resolves label addresses, optimizes the performance and generates the specific x86-64 machine code from the generic instruction set.
+
+The `Run` method is currently not fully implemented.
 
 ## Tests