From a78d560a0d6d61b43d5ca61d21fc23ba5a80d2fb Mon Sep 17 00:00:00 2001
From: Jeff <dev@jeffa.io>
Date: Tue, 13 Aug 2024 18:27:03 -0400
Subject: [PATCH] Add docs

---
 dust-lang/src/abstract_tree.rs | 10 +++++++---
 dust-lang/src/lib.rs           | 16 +++++++++++++++-
 dust-lang/src/vm.rs            |  6 ++++++
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/dust-lang/src/abstract_tree.rs b/dust-lang/src/abstract_tree.rs
index 7cd22ef..2700e47 100644
--- a/dust-lang/src/abstract_tree.rs
+++ b/dust-lang/src/abstract_tree.rs
@@ -34,6 +34,7 @@ impl<T: Display> Display for Node<T> {
 
 #[derive(Debug, Clone, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
 pub enum Statement {
+    // Assignment does not return a value, but has a side effect on the context
     Assignment {
         identifier: Node<Identifier>,
         operator: Node<AssignmentOperator>,
@@ -43,7 +44,7 @@ pub enum Statement {
     // A sequence of statements
     Block(Vec<Node<Statement>>),
 
-    // Assignment, logic, math and comparison expressions with two operands
+    // Logic, math and comparison expressions with two operands
     BinaryOperation {
         left: Box<Node<Statement>>,
         operator: Node<BinaryOperator>,
@@ -100,7 +101,10 @@ pub enum Statement {
         else_body: Box<Node<Statement>>,
     },
 
-    // Identifier expression
+    // Identifier
+    //
+    // Identifier statements in the syntax tree (i.e. Node<Statement>) are evaluated as
+    // expressions or reconstructed into a Node<Identifier> by the parser
     Identifier(Identifier),
 
     // Value collection expressions
@@ -111,7 +115,7 @@ pub enum Statement {
     Constant(Value),
 
     // A statement that always returns None. Created with a semicolon, it causes the preceding
-    // statement to return None. This is analagous to the semicolon or unit type in Rust.
+    // statement to return None. This is analagous to the semicolon in Rust.
     Nil(Box<Node<Statement>>),
 }
 
diff --git a/dust-lang/src/lib.rs b/dust-lang/src/lib.rs
index 2a4deff..f8bd0d7 100644
--- a/dust-lang/src/lib.rs
+++ b/dust-lang/src/lib.rs
@@ -1,6 +1,20 @@
 //! The Dust programming language.
 //!
-//! Dust is a statically typed, interpreted programming language.
+//! To get started, you can use the `run` function to run a Dust program.
+//!
+//! ```rust
+//! use dust_lang::{run, Value};
+//!
+//! let program = "
+//!     foo = 21
+//!     bar = 2
+//!     foo * bar
+//! ";
+//!
+//! let the_answer = run(program).unwrap();
+//!
+//! assert_eq!(the_answer, Some(Value::integer(42)));
+//! ```
 pub mod abstract_tree;
 pub mod analyzer;
 pub mod built_in_function;
diff --git a/dust-lang/src/vm.rs b/dust-lang/src/vm.rs
index f8b46c3..29481f9 100644
--- a/dust-lang/src/vm.rs
+++ b/dust-lang/src/vm.rs
@@ -63,6 +63,12 @@ pub fn run_with_context(source: &str, context: Context) -> Result<Option<Value>,
         .map_err(|vm_error| DustError::VmError { vm_error, source })
 }
 
+/// Dust virtual machine.
+///
+/// **Warning**: Do not run an AbstractSyntaxTree that has not been analyzed. Use the `run` or
+/// `run_with_context` functions to make sure the program is analyzed before running it.
+///
+/// See the `run_with_context` function for an example of how to use the Analyzer and the VM.
 pub struct Vm {
     abstract_tree: AbstractSyntaxTree,
     context: Context,