docs: add docs

src/eval.rs

@@ -52,17 +52,9 @@ pub enum Value {
         callee: Box<Value>,
         arguments: Vec<Value>,
     },
-    Def {
-        name: Keyword,
-        value: Box<Value>,
-    },
-    DefMacro {
-        name: Keyword,
-        value: Box<Value>,
-    },
-    Recur {
-        arguments: Vec<Value>,
-    },
+    Def(Keyword, Box<Value>),
+    DefMacro(Keyword, Box<Value>),
+    Recur(Vec<Value>),
     Quote(Expr),
     Ptr(*mut ()),
     Nil,
@@ -135,6 +127,8 @@ impl Environment {
     }
 }
 
+/// A trampoline for evaluation. It's treated like a result, but it can also
+/// contain a continuation.
 pub enum Trampoline<T, E = Expr> {
     Done(T),
     Raise(E),
@@ -236,26 +230,26 @@ impl Expr {
             // Base cases for expansion when it will just walk the tree. These
             // are the cases where the expansion is recursive.
             Expr::List(list) => Ok(Value::List(
-                list.elements()?
+                /* elements: */ list.elements()?
                     .into_iter()
                     .map(|expr| expr.expand(environment))
                     .collect::<Result<Vec<_>, _>>()?,
             )),
-            Expr::Def(def) => Ok(Value::Def {
-                name: def.name()?.expand(environment)?.try_into()?,
-                value: def.value()?.expand(environment)?.into(),
-            }),
-            Expr::Recur(recur) => Ok(Value::Recur {
-                arguments: recur
+            Expr::Def(def) => Ok(Value::Def(
+                /* name : */ def.name()?.expand(environment)?.try_into()?,
+                /* value: */ def.value()?.expand(environment)?.into(),
+            )),
+            Expr::Recur(recur) => Ok(Value::Recur(
+                /* arguments: */ recur
                     .spine()?
                     .into_iter()
                     .map(|expr| expr.expand(environment))
                     .collect::<Result<Vec<_>, _>>()?,
-            }),
-            Expr::DefMacro(def_macro) => Ok(Value::DefMacro {
-                name: def_macro.name()?.expand(environment)?.try_into()?,
-                value: def_macro.value()?.expand(environment)?.into(),
-            }),
+            )),
+            Expr::DefMacro(def_macro) => Ok(Value::DefMacro(
+                /* name : */ def_macro.name()?.expand(environment)?.try_into()?,
+                /* value: */ def_macro.value()?.expand(environment)?.into(),
+            )),
 
             // Expansion of literal terms, just wrap them in a value. This is
             // the base case of the expansion.

src/lib.rs

@@ -3,10 +3,15 @@
 
 use std::fmt::Display;
 
+pub type Result<T, E = SemanticError> = std::result::Result<T, E>;
+
+/// Evaluation of the Soft programming language, it will transform an [crate::Expr] into
+/// a [crate::eval::Value].
 pub mod eval;
-pub mod parser;
 
-pub type Result<T, E = SemanticError> = std::result::Result<T, E>;
+/// Tokenization/lexing and parsing of Soft programming language, it will transform a string
+/// into [crate::Term].
+pub mod parser;
 
 /// Term is a recursive data structure that represents a list of terms, an atom, an identifier,
 /// or an integer.
@@ -30,6 +35,9 @@ pub trait ExprKind: Sized {
 
 // Abstract-Syntax-Tree (AST) for the Soft programming language. It's the representation
 // of abstract terms in the language.
+//
+// It's the specialized phase of the language, where we have a concrete syntax and we
+// can start to evaluate the program.
 define_ast!(Expr, {
     Fun,      // (fun* [a b] (+ a b))
     List,     // [a b c] or (list a b c)