more docs

src/README.md

@@ -0,0 +1,19 @@
+
+The source files directly contained by this folder expose to the user through the command line the functionalities implemented inside the subfolders.
+
+The `main.c` function is the entry of the source and, based on the options provided by the user, executes, parses or disassembles the source code. Inside `debug.c` is implemented the callback that `main.c` provides to the runtime if the user asks for an execution in debug mode that makes it possible to expose the internal state of the interpreter during the execution.
+
+The `utils` folder contains the implementations of general purpose data structures and definitions that are useful through all of the codebase. Some of the more used data structures are:
+
+* `BPAlloc`: A bump-pointer allocator.
+* `Error`: A structure useful to report errors to function callers.
+* `Source`: A string object that is used in place of raw strings to move source code around.
+
+The `common` folder implements the `Executable` data structure, which contains the result of a source's compilation. It can be though about as an array of bytecode instructions that can be directly executed. 
+
+The `compiler` folder implements the compiler of the interpreter. The main routine that is exported from here is `compile`, which transform a `Source` into an `Executable`. Other functions are exported like `serialize` that transforms an `AST` in JSON format. This subfolder is the only part of the codebase that should be able to access the `AST` nodes.
+
+The `objects` folder implements the object model. In the context of this language, an object is a virtual class that implements a given set of methods. This folder exports functions that transform "raw" data types into objects, functions that do the inverse transformation and functions that trigger the virtual methods. This folder also contains the implementation of the heap and the garbage collector that needs to be tightly coupled with the object model.
+
+The `runtime` folder implements the routines that execute the `Executable`s. It depends heavily on `objects`.
+

src/compiler/compile.c

@@ -9,7 +9,8 @@
  * which walks the tree and writes instructions to the `ExeBuilder`.
  *   Some semantic errors are catched at this phase, in which 
  * case, they are reported by filling out the `error` structure 
- * and aborting.
+ * and aborting. It's also possible that the compilation fails
+ * bacause of internal errors (which usually means "out of memory").
  *
  */
 
@@ -505,6 +506,26 @@ static _Bool emit_instr_for_node(ExeBuilder *exeb, Node *node, Error *error)
 	return 0;
 }
 
+/* Symbol: compile
+ * 
+ *   Serializes an AST into bytecode format.
+ *
+ *
+ * Arguments:
+ *
+ *   ast: The AST to be serialized.
+ *   alloc: The allocator that will be used to get new
+ *			memory. (optional)
+ *   error: Error information structure that is filled out if
+ *          an error occurres.
+ *
+ *
+ * Returns:
+ *   A pointer to an `Executable` that is the object that
+ *	 contains the bytecode. If an error occurres, NULL is 
+ *   returned and the `error` structure is filled out.
+ *
+ */
 Executable *compile(AST *ast, BPAlloc *alloc, Error *error)
 {
 	assert(ast != NULL);