From ffeec8e192a31231854af2621344f9b9054623dd Mon Sep 17 00:00:00 2001
From: Nilstrieb <48135649+Nilstrieb@users.noreply.github.com>
Date: Sat, 1 Jan 2022 15:12:26 +0100
Subject: [PATCH] docs

---
 src/bytecode.rs | 26 ++++++++++++++++++++++++++
 src/gc.rs       |  4 +++-
 src/lib.rs      |  1 +
 3 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/src/bytecode.rs b/src/bytecode.rs
index 51146d2..b6f100a 100644
--- a/src/bytecode.rs
+++ b/src/bytecode.rs
@@ -1,19 +1,43 @@
 //! The bytecode that is executed in the vm
+//!
+//! # Details
+//!
+//! ## Function Blocks
+//! Every function is compiled into a bytecode block. These blocks are self-contained, and contain
+//! all debug- and other information associated with it. The final bytecode is a collection of
+//! these blocks.
+//!
+//! Note: Because of closures, function blocks have more required inputs than just the parameters,
+//! but the compiler should handle that correctly.
+//!
+//! ## Local offsets
+//! Variables offsets are calculated as `local offsets`. Local offsets are calculated relative to
+//! the start of the space of the stack required by that function. The interpreter must keep track
+//! of the stack start of each function, to be able to calculate these offsets.
 
 use crate::errors::Span;
 use crate::vm::Value;
 use bumpalo::collections::Vec;
 
+/// This struct contains all data for a function.
 #[derive(Debug)]
 pub struct FnBlock<'bc> {
+    /// The bytecode of the function
     pub code: Vec<'bc, Instr>,
+    /// The sizes of the stack required by the function at each instruction. This is only used
+    /// during compilation to calculate local variable offsets.
     pub stack_sizes: Vec<'bc, usize>,
+    /// The corresponding source code location of each instruction. This is debuginfo and only
+    /// used if there are errors.
     pub spans: Vec<'bc, Span>,
+    /// How many parameters the function accepts.
     pub arity: u8,
 }
 
+/// A bytecode instruction. For more details on the structure of the bytecode, read the module level docs [`bytecode`](`self`)
 #[derive(Debug, Clone, Copy)]
 pub enum Instr {
+    /// An operation that does nothing.
     Nop,
 
     /// Store the current value on the stack to the stack location with the local offset `usize`
@@ -24,6 +48,8 @@ pub enum Instr {
     PushVal(Value),
     /// Negate the top value on the stack. Only works with numbers and booleans
     Neg,
+
+    // The binary operations. The `rhs` is on top of the stack, and `lhs` is below it
     BinAdd,
     BinSub,
     BinMul,
diff --git a/src/gc.rs b/src/gc.rs
index 9098445..9a0a0d8 100644
--- a/src/gc.rs
+++ b/src/gc.rs
@@ -1,4 +1,6 @@
-#![allow(dead_code)]
+//! The garbage collector for the language
+//!
+//! The structure of the GC might change, but for now it's simply a `LinkedList` of `Object`s.
 
 use crate::vm::Value;
 use crate::{HashMap, HashSet};
diff --git a/src/lib.rs b/src/lib.rs
index 2a61658..ff67f11 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 #![deny(clippy::disallowed_type)]
 
 mod ast;