ft: add debug script

src/operands.rs

@@ -1,6 +1,10 @@
 //! All types which a Mnemonic can have as some kind of operand.
 //! This includes things such as immediates, ModRM byte targets, etc. etc.
 
+// used in doc, but not code
+#[allow(unused_imports)]
+use crate::register::SegmentRegister;
+
 use crate::{disasm::DisasmError, register::Register};
 use core::fmt;
 
@@ -39,7 +43,8 @@ impl fmt::LowerHex for Operand {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-/// ModRM byte can either target a memory location or some register.
+/// ModRM byte can either target a [`MemoryIndex`] (location in memory) or some
+/// [`Register`].
 pub enum ModRmTarget {
     Memory(MemoryIndex),
     Register(Register),
@@ -57,6 +62,12 @@ impl std::fmt::Display for ModRmTarget {
 #[derive(Debug, Clone, PartialEq, Eq)]
 /// Memory displacements are signed versions of Byte and Word operands.
 /// Encodes either Byte- or Word-sized operands.
+/// Generally, a [`Displacement`] is the result of a ModRM byte parse and
+/// usually really is the signed displacement of a [`MemoryIndex`] for memory
+/// operations.
+/// Although, some instructions use this parsed displacement as an unsigned
+/// pointer, hence the [`Displacement`] will be cast to [`Pointer16`], when this
+/// is the case.
 pub enum Displacement {
     IByte(IByte),
     IWord(IWord),
@@ -133,6 +144,8 @@ impl fmt::Display for MemoryIndex {
 #[derive(Debug, Clone, PartialEq, Eq)]
 /// 16-bit pointer for access, usually with a [`SegmentRegister`]  as segment
 /// and [`Pointer16`] as offset.
+/// Generally, this type only gets constructed in rare scenarios, when the
+/// [`Displacement`] of ModRM byte is used as a raw pointer.
 pub struct Pointer16 {
     pub word: Word,
 }
@@ -152,15 +165,21 @@ impl TryFrom<ModRmTarget> for Pointer16 {
                 Some(disp) => match disp {
                     Displacement::IWord(word) => Ok(Pointer16 { word: word as Word }),
                     _ => {
-                        return Err(DisasmError::IllegalOperand("Word expected".into()));
+                        return Err(DisasmError::IllegalOperand(
+                            "Tried to construct Pointer16 with Byte, when a Word is expected"
+                                .into(),
+                        ));
                     }
                 },
                 _ => {
-                    return Err(DisasmError::IllegalOperand("Displacement expected".into()));
+                    return Err(DisasmError::IllegalOperand("Tried to construct Pointer16 with Register, when a Displacement was expected".into()));
                 }
             },
             _ => {
-                return Err(DisasmError::IllegalOperand("MemoryIndex expected".into()));
+                return Err(DisasmError::IllegalOperand(
+                    "Tried to construct Pointer16 with Register, when a MemoryIndex expected"
+                        .into(),
+                ));
             }
         }
     }