diff --git a/Cargo.lock b/Cargo.lock
index 7cddc37..7faf62e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4,13 +4,13 @@ version = 3
 
 [[package]]
 name = "phoron_asm"
-version = "1.0.0"
+version = "1.0.2"
 dependencies = [
  "phoron_core",
 ]
 
 [[package]]
 name = "phoron_core"
-version = "0.5.3"
+version = "0.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b792ef6aecacbb5ede70f16cde879b00fc992ed084f3655f7d95b6bed19b5c14"
+checksum = "25d51efca1234563a111e9713d61e72aefad7af4f8aea8ac0da8ae48c0b5bdd1"
diff --git a/Cargo.toml b/Cargo.toml
index c2c5269..45068b1 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,10 +1,10 @@
 [package]
 name = "phoron_asm"
 description = "A Jasmin-compatible Assembler for the JVM"
-version = "1.0.1"
+version = "1.0.2"
 authors = ["Timmy Jose"]
 homepage = "https://github.com/oyi-lang/phoron_asm"
-documentation = "https://docs.rs/phoron_asm/1.0.0/phoron_asm/"
+documentation = "https://docs.rs/phoron_asm/1.0.2/phoron_asm/"
 repository = "https://github.com/oyi-lang/phoron_asm"
 readme = "README.md"
 license-file = "LICENSE"
diff --git a/README.md b/README.md
index 6a5cf69..f43a5d7 100644
--- a/README.md
+++ b/README.md
@@ -201,7 +201,7 @@ Running it:
 $ cargo run --release
 Class file generated
 
-:$ javap -v samples/HelloWorld.class
+$ javap -v samples/HelloWorld.class
 Classfile /Users/z0ltan/dev/playground/phoron_asm_demo/samples/HelloWorld.class
   Last modified 19-Mar-2023; size 389 bytes
   SHA-256 checksum 533a66c051831cba84a32b20d38c4bb20d68b78aabc137d7c7fb3cc864ff8bf9
@@ -263,7 +263,7 @@ Constant pool:
 }
 SourceFile: "./samples/HelloWorld.pho"
 
-~/dev/playground/phoron_asm_demo:$ java -cp "./samples" HelloWorld
+$ java -cp "./samples" HelloWorld
 Hello, world
 
 ```
diff --git a/src/ast/mod.rs b/src/ast/mod.rs
index 7fde136..e1f3bb8 100644
--- a/src/ast/mod.rs
+++ b/src/ast/mod.rs
@@ -1,3 +1,8 @@
+//! The Phoron AST.
+//!
+//! The model is kept as simple as possible in order to allow provide good type-checking as well as
+//! east and direct translation into the  `ClassFile` format required by the `Codegen` module.
+
 use std::default::Default;
 
 pub mod attributes;
diff --git a/src/codegen.rs b/src/codegen.rs
index 4362bf5..63092d7 100644
--- a/src/codegen.rs
+++ b/src/codegen.rs
@@ -1,3 +1,5 @@
+//! The interface to `phoron_core`. This module constructs the `ClassFile` object needed by
+//! `phoron_core` in order to generate the actual `class` file.
 use crate::{
     ast::{attributes::*, *},
     cp_analyzer::constant_pool::*,
diff --git a/src/cp_analyzer/mod.rs b/src/cp_analyzer/mod.rs
index 372ad1f..3a56758 100644
--- a/src/cp_analyzer/mod.rs
+++ b/src/cp_analyzer/mod.rs
@@ -1,3 +1,9 @@
+//! A Phoron abstraction of the JVM's  Constant Pool (arguably the most important aspect of the JVM
+//! bytecode format).
+//!
+//! The indxeing of the Constant Pool elements is deterministic (the ordering is left unspecified
+//! in the JVM specification) and follows a top-down recursive approach.
+//!
 use crate::ast::{attributes::*, *};
 
 pub mod constant_pool;
diff --git a/src/diagnostics/mod.rs b/src/diagnostics/mod.rs
index e41ce1c..c1c2015 100644
--- a/src/diagnostics/mod.rs
+++ b/src/diagnostics/mod.rs
@@ -1,3 +1,7 @@
+//! A simple diagnostic module for Phoron.
+//!
+//! Provides formatted error reporting via the `emitter` submodule as well as a fail-fast version
+//! that exits immediately.
 use crate::sourcefile::{Location, SourceFile, Span};
 use std::error::Error;
 
diff --git a/src/lexer/mod.rs b/src/lexer/mod.rs
index 19c7fa8..0da3bab 100644
--- a/src/lexer/mod.rs
+++ b/src/lexer/mod.rs
@@ -1,3 +1,6 @@
+//! Takes a `SourceFile` representing the assembly source code, and produces a stream of tokens
+//! for consumption by the parser.
+
 use std::{
     error::Error,
     fmt,
diff --git a/src/lexer/token.rs b/src/lexer/token.rs
index 4d906fb..6840767 100644
--- a/src/lexer/token.rs
+++ b/src/lexer/token.rs
@@ -1,3 +1,6 @@
+//! Represents a valid token in the Phoron (Jasmin) assembly language.
+//! Unlike Jasmin, each JVM opcode becomes its own type enabling better type-checking and error
+//! reporting.
 use crate::sourcefile::Span;
 
 #[derive(Debug)]
diff --git a/src/lib.rs b/src/lib.rs
index d39114c..3667632 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,9 @@
+//! `Phoron` is a [Jasmin](https://jasmin.sourceforge.net/) compatible assembler for the JVM.
+//!
+//! `phoron_asm` provides the actual assembler for the assembly language whereas `phoron_core`
+//! handles the low-level `class` file serialisation and deserialisation.
+//!
+
 pub mod ast;
 pub mod codegen;
 pub mod cp_analyzer;
diff --git a/src/parser/levenshtein.rs b/src/parser/levenshtein.rs
index 9728d94..c939a1c 100644
--- a/src/parser/levenshtein.rs
+++ b/src/parser/levenshtein.rs
@@ -1,3 +1,10 @@
+//! A utility module to provide suggestions for possibly misspelt JVM opcodes. Since the assembly
+//! language allows a lot of overlap in terms of labels, opcodes, and other syntactic elements,
+//! type-checking is necessarily more difficult especially when coupled with error recovery via
+//! skipping tokens (panic mode).
+//! This module calculates the Levenshtein distance between a (possible) label and a JVM opcode,
+//! and given a sufficient probability, provides recommendations of the closest matching JVM
+//! opcode.
 use std::cmp::{max, min};
 
 const LEVENSHTEIN_THRESHOLD: f64 = 0.50;
diff --git a/src/parser/mod.rs b/src/parser/mod.rs
index ec0fd14..2fdefd0 100644
--- a/src/parser/mod.rs
+++ b/src/parser/mod.rs
@@ -1,3 +1,7 @@
+//! The Phoron Parser takes in a lexer and produces a token on demand (syntax-driven).
+//! It also uses the `Span` information collected during tokenisation to provide goood
+//! error recovery and error reporting.
+
 use crate::{
     ast::*,
     diagnostics::DiagnosticManager,
diff --git a/src/parser/type_descriptor_parser.rs b/src/parser/type_descriptor_parser.rs
index 1e8fd1c..d35bf4f 100644
--- a/src/parser/type_descriptor_parser.rs
+++ b/src/parser/type_descriptor_parser.rs
@@ -1,4 +1,4 @@
-//! A parser for type descriptors as per the JVM specification
+//! A parser for type descriptors as per the JVM specification.
 
 use crate::ast::{PhoronBaseType, PhoronFieldDescriptor, PhoronReturnDescriptor};
 use std::{error::Error, fmt, iter::Peekable, str::Chars};
diff --git a/src/sourcefile.rs b/src/sourcefile.rs
index 10752f7..e5ae85f 100644
--- a/src/sourcefile.rs
+++ b/src/sourcefile.rs
@@ -1,3 +1,7 @@
+//! Abstract representation of a physical source file in the file system. The `SourceFile` is
+//! used by the lexer for tokenisation, as well as to provide `Span`s over the actual source code
+//! for error reporting during parsing and type-checking.
+
 use std::{convert::From, fmt::Debug, fs, io, ops::Sub, path::Path};
 
 /// Absolute offset from the beginning of the byte stream