Improved documentation

src/build/readme.md

@@ -0,0 +1,19 @@
+### [Build.go](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 `.q` source files in the build directory.
+Every source file is scanned in its own goroutine for performance reasons.
+Parallelization here is possible because the order of files in a directory is not significant.
+
+The main thread is meanwhile waiting for new function objects to arrive from the scanners.
+Once a function has arrived, it will be stored for compilation later.
+We need to wait with the compilation step until we have enough information about all identifiers from the scan.
+
+Then all the functions that were scanned will be compiled in parallel.
+We create a separate goroutine for each function compilation.
+Each function will then be translated to generic assembler instructions.
+
+All the functions that are required to run the program will be added to the final assembler.
+The final assembler resolves label addresses, optimizes the performance and generates the specific machine code from the generic instruction set.

src/cli/readme.md

@@ -0,0 +1,34 @@
+### [Main.go](Main.go)
+
+Entry point.
+
+The command line interface expects a command like `build` as the first argument.
+Commands are implemented as functions in the `cli` directory.
+Each command has its own set of parameters.
+
+### [Build.go](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
+```
+
+Adding the `-a` or `--assembler` flag shows the generated assembly instructions:
+
+```shell
+q build examples/hello -a
+```
+
+Adding the `-v` or `--verbose` flag shows verbose compiler information:
+
+```shell
+q build examples/hello -v
+```

src/core/readme.md

@@ -0,0 +1,5 @@
+## [Function.go](Function.go)
+
+This is the "heart" of the compiler.
+Each function runs [Compile](Compile.go) which organizes the source code into an abstract syntax tree that is then compiled via [CompileAST](CompileAST.go).
+You can think of AST nodes as the individual statements in your source code.

src/readme.md

@@ -25,74 +25,3 @@
 - [token](token) - Converts a file to tokens with the `Tokenize` function
 - [types](types) - Type system (w.i.p.)
 - [x64](x64) - x86-64 implementation
-
-# Documentation
-
-## [cli/Main.go](cli/Main.go)
-
-Entry point.
-
-The command line interface expects a command like `build` as the first argument.
-Commands are implemented as functions in the [cli](cli) directory.
-Each command has its own set of parameters.
-
-## [cli/Build.go](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
-```
-
-Adding the `-a` or `--assembler` flag shows the generated assembly instructions:
-
-```shell
-q build examples/hello -a
-```
-
-Adding the `-v` or `--verbose` flag shows verbose compiler information:
-
-```shell
-q build examples/hello -v
-```
-
-## [build/Build.go](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 `.q` source files in the build directory.
-Every source file is scanned in its own goroutine for performance reasons.
-Parallelization here is possible because the order of files in a directory is not significant.
-
-The main thread is meanwhile waiting for new function objects to arrive from the scanners.
-Once a function has arrived, it will be stored for compilation later.
-We need to wait with the compilation step until we have enough information about all identifiers from the scan.
-
-Then all the functions that were scanned will be compiled in parallel.
-We create a separate goroutine for each function compilation.
-Each function will then be translated to generic assembler instructions.
-
-All the functions that are required to run the program will be added to the final assembler.
-The final assembler resolves label addresses, optimizes the performance and generates the specific machine code from the generic instruction set.
-
-## [core/Function.go](core/Function.go)
-
-This is the "heart" of the compiler.
-Each function runs `f.Compile` which organizes the source code into an abstract syntax tree that is then compiled via `f.CompileAST`.
-You can think of AST nodes as the individual statements in your source code.
-
-## [ast/Parse.go](ast/Parse.go)
-
-This is what generates the AST from tokens.
-
-## [expression/Parse.go](expression/Parse.go)
-
-This is what generates expressions from tokens.