docs(lib): add docs

lib/src/exec/debug.rs

@@ -13,9 +13,9 @@ use crate::parse::Span;
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 #[cfg_attr(feature = "bincode", derive(Encode, Decode))]
 pub struct DebugInfo {
-    /// Orginal labels of instructions
+    /// Original labels of instructions
     pub prog: BTreeMap<usize, String>,
-    /// Orignal labels of memory entries
+    /// Original labels of memory entries
     pub mem: BTreeMap<usize, String>,
     /// Portions of source recognised as instructions
     pub inst_spans: Vec<Span>,

lib/src/exec/mod.rs

@@ -66,14 +66,17 @@ pub struct Io {
 
 /// Quickly makes an [`Io`] struct
 ///
-/// $read must implement [`Read`].
-/// $write must implement [`Write`].
+/// # Arguments (optional)
+///
+/// * `$read`: must implement [`Read`].
+/// * `$write`: must implement [`Write`].
 ///
 /// # Example
 /// ```
 /// use cambridge_asm::make_io;
 ///
-/// let io = make_io!(std::io::stdin(), std::io::sink());
+/// let default_io = make_io!(); // no macro arguments will give the default I/O provider, i.e. stdio
+/// let io = make_io!(std::io::stdin(), std::io::sink()); // you can use your own providers too
 /// ```
 #[macro_export]
 macro_rules! make_io {
@@ -165,8 +168,28 @@ impl Context {
         }
     }
 
+    /// Read the given operand from the context
+    ///
+    /// # Arguments
+    ///
+    /// * `op`:
+    ///
+    /// returns: `RtResult`
+    ///
     /// # Panics
-    /// if `op` is not usizeable. To avoid this, check `op` using [`Op::is_usizeable`]
+    ///
+    /// If `op` is not usizeable. To avoid this, check `op` using [`Op::is_usizeable`]
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use cambridge_asm::inst;
+    /// inst!(print (ctx, op) {
+    ///     if op.is_usizeable() {
+    ///         println!("{}", ctx.read(op)?);
+    ///     }
+    /// });
+    /// ```
     #[inline]
     pub fn read(&self, op: &Op) -> RtResult<usize> {
         match op {
@@ -181,8 +204,29 @@ impl Context {
         }
     }
 
+    /// Modify the given operand in the context if it is writeable
+    ///
+    /// # Arguments
+    ///
+    /// * `op`: operand
+    /// * `f`: closure to modify the value
+    ///
+    /// returns: [`RtResult`]
+    ///
     /// # Panics
-    /// If `op` is not writable. To avoid this, check `op` using [`Op::is_read_write`].
+    ///
+    /// If `op` is not writeable. To avoid this, check `op` using [`Op::is_read_write`].
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use cambridge_asm::inst;
+    /// inst!(double_inc (ctx, op) {
+    ///     if op.is_read_write() {
+    ///         ctx.modify(op, |val| *val += 2)?;
+    ///     }
+    /// });
+    /// ```
     #[inline]
     pub fn modify(&mut self, op: &Op, f: impl Fn(&mut usize)) -> RtResult {
         match op {
@@ -266,7 +310,12 @@ impl Executor {
         }
     }
 
-    /// Advances execution by one instruction
+    /// Advance execution by one instruction
+    ///
+    /// # Example
+    /// ```no_run
+    ///
+    /// ```
     pub fn step<T>(&mut self) -> Status
     where
         T: InstSet,

lib/src/parse/mod.rs

@@ -19,7 +19,16 @@ pub use lexer::{ErrorKind, ErrorMap, Span};
 inst_set! {
     /// The core instruction set
     ///
-    /// Basic instructions only
+    /// * Memory and register manipulation:
+    /// `LDM`, `LDD`, `LDI`, `LDX`, `LDR`, `MOV`, `STO`
+    ///
+    /// * Comparison: `CMP`, `JPE`, `JPN`, `JMP`, `CMI`
+    ///
+    /// * Basic I/O: `IN`, `OUT`, `END`
+    ///
+    /// * Arithmetic: `INC`, `DEC`, `ADD`, `SUB`
+    ///
+    /// * Bit manipulation: `AND`, `OR`, `XOR`, `LSL`, `LSR`
     pub Core use crate::exec::{mov, cmp, io, arith, bitman}; {
         LDM => mov::ldm,
         LDD => mov::ldd,
@@ -55,7 +64,7 @@ inst_set! {
 extend! {
     /// The extended instruction set
     ///
-    /// [`Core`], plus debugging, raw input, function call and return, and no-op instructions
+    /// [`Core`], plus debugging (`DBG`), raw input (`RIN`), function `CALL` and return (`RET`), and no-op (`NOP`) instructions
     #[cfg(feature = "extended")]
     pub Extended extends Core use crate::exec::{io, arith::zero}; {
         ZERO => zero,
@@ -113,9 +122,27 @@ where
     Ok((prog, mem, src, debug_info))
 }
 
-/// Parses a string into an [`Executor`]
+/// Parse a string into an [`Executor`]
+///
+/// # Arguments
+///
+/// * `T`: instruction set
+/// * `prog`: pseudo-assembly program
+/// * `io`: I/O provider, use [`make_io`]
+///
+/// returns: `Result<Executor, ErrorMap>`
+///
+/// # Example
 ///
-/// This is the primary method to parse a pseudoassembly program
+/// ```no_run
+/// # use cambridge_asm::make_io;
+/// # use cambridge_asm::parse::{ErrorMap, Extended, jit};
+///
+/// # fn foo(s: String) -> Result<(), ErrorMap> {
+/// let exec = jit::<Extended>(s, make_io!())?;
+/// # Ok(())
+/// # }
+/// ```
 pub fn jit<T>(prog: impl Deref<Target = str>, io: Io) -> Result<Executor, ErrorMap>
 where
     T: InstSet,
@@ -137,7 +164,27 @@ where
     Ok(exe)
 }
 
-/// Parses a string into an [`Executor`] directly from a file
+/// Parse a file into an [`Executor`]
+///
+/// # Arguments
+///
+/// * `T`: instruction set
+/// * `path`: path to file containing pseudo-assembly program
+/// * `io`: I/O provider, use [`make_io`]
+///
+/// returns: `Result<Executor, ErrorMap>`
+///
+/// # Example
+///
+/// ```no_run
+/// # use cambridge_asm::make_io;
+/// # use cambridge_asm::parse::{ErrorMap, Extended, jit_from_file};
+///
+/// # fn foo(path: String) -> Result<(), ErrorMap> {
+/// let exec = jit_from_file::<Extended>(path, make_io!())?;
+/// # Ok(())
+/// # }
+/// ```
 pub fn jit_from_file<T>(path: impl AsRef<Path>, io: Io) -> Result<Executor, ErrorMap>
 where
     T: InstSet,
@@ -192,7 +239,9 @@ mod parse_tests {
     }
 
     #[test]
-    #[should_panic]
+    #[should_panic(
+        expected = "called `Result::unwrap()` on an `Err` value: {4..7: ParseIntError(ParseIntError { kind: InvalidDigit })}"
+    )]
     fn panics() {
         let mut exec = jit::<DefaultSet>(
             include_str!("../../examples/panics.pasm"),