From b3af047d3a9b0c0e7465c660b512cd5b5aa87ca2 Mon Sep 17 00:00:00 2001
From: John Breaux <j@soft.fish>
Date: Tue, 22 Aug 2023 23:59:17 -0500
Subject: [PATCH] error.rs: Document errors & error messages

---
 src/error.rs | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/src/error.rs b/src/error.rs
index 1a9c96c..e6ca794 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,5 +1,5 @@
-// © 2023 John Breaux
-// TODO: Be incredibly specific about the source of the errors
+// © 2023 John Breauxs
+//! Common error type for [msp430-asm](crate) errors
 
 use std::fmt::Display;
 
@@ -8,7 +8,7 @@ use super::{
     *,
 };
 
-// TODO: Store error context in error. for example:
+// TODO: Store more error context in error. for example:
 // Error {ExpectationFailed{...}, WhileParsing(Register)}
 
 #[derive(Debug)]
@@ -37,11 +37,23 @@ pub enum Error {
     ///
     /// This should be interpreted as a failure in lexing.
     UnrecognizedOpcode(String),
+    /// Produced by [Register](parser::instruction::encoding::register::Register)
+    /// when attempting to convert from a [str] that isn't a register (pc, sp, sr, cg, or r{number})
     NotARegister(String),
+    /// Produced by [Register](parser::instruction::encoding::register)
+    /// when attempting to convert from a [u16] that isn't in the range 0-15
     RegisterTooHigh(u16),
+    /// Produced by
+    /// [SecondaryOperand](parser::instruction::encoding::secondary_operand)
+    /// when the joke "secondary immediate" form is specified
     FatSecondaryImmediate(isize),
+    /// Produced by [Number](parser::instruction::encoding::number) when the number is too
+    /// wide to fit in 16 bits (outside the range `(-2^15) .. (2^16-1)` )
     NumberTooWide(isize),
+    /// Produced by [JumpTarget](parser::instruction::encoding::jump_target)
+    /// when the jump offset is outside the range (-0x3ff..0x3fc)
     JumpedTooFar(isize),
+    /// Produced by [JumpTarget](parser::instruction::encoding::jump_target)
     JumpedOdd(isize),
     EndOfFile,
 }
@@ -90,8 +102,8 @@ impl Display for Error {
             Error::RegisterTooHigh(reg) => write!(f, "r{reg} is not a register"),
             Error::FatSecondaryImmediate(num) => write!(f, "Secondary immediate must be #0 or #1, not #{num}"),
             Error::NumberTooWide(num) => write!(f, "{num} does not fit in 16 bits"),
-            Error::JumpedTooFar(num) => write!(f, "{num} is too far away (jump targets must be in range (-3fc..=3fe"),
-            Error::JumpedOdd(num) => write!(f, "Jump target {num} should not be odd."),
+            Error::JumpedTooFar(num) => write!(f, "{num} is too far away: must be in range (`-1022..=1024`.)"),
+            Error::JumpedOdd(num) => write!(f, "Jump targets only encode even numbers: {num} must not be odd."),
             Error::EndOfFile => write!(f, "Unexpected end of file"),
         }
     }