Minimal documentation for phoron_asm

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"

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
 
 ```

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;

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::*,

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;

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;
 

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,

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)]

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;

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;

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,

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};

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