parser: Improve module-level doc comments

src/parser/comment.rs

@@ -1,4 +1,5 @@
 // © 2023 John Breaux
+//! A [Comment] stores the contents of a line comment, including the preceding `;` or `//`
 use super::*;
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Comment(pub String);

src/parser/identifier.rs

@@ -1,4 +1,5 @@
 // © 2023 John Breaux
+//! An [Identifier] stores the hash of a named identifier
 use super::*;
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Identifier {
@@ -20,7 +21,7 @@ impl Parsable for Identifier {
         let token = stream.expect(Type::Identifier)?;
         match token.variant() {
             Type::Identifier => Ok(Self::str(token.lexeme())),
-            _ => unreachable!("Expected Identifier, got {token:?}"),
+            _ => unreachable!("Expected identifier, got {token:?}"),
         }
     }
 }

src/parser/instruction.rs

@@ -1,13 +1,13 @@
 // © 2023 John Breaux
 //! An [Instruction] contains the [Opcode] and [Encoding] information for a single msp430
 //! instruction
-//! 
+//!
-//! 
+//!
-//! Note: [Opcode] and [Encoding] are very tightly coupled, because they represent interdependent parts
+//! Note: [Opcode] and [Encoding] are very tightly coupled, because they represent interdependent
-//! of the same instruction. This is why [Opcode]::resolve() returns an [EncodingParser] -- otherwise,
+//! parts of the same instruction. This is why [Opcode]::resolve() returns an [EncodingParser] --
-//! there's an explosion of states that I can't really cope with on my own. Really, there's about 9
+//! otherwise, there's an explosion of states that I can't really cope with on my own. Really,
-//! valid classes of instruction, some of which are only used for one or two of the MSP430's
+//! there's about 9 valid classes of instruction, some of which are only used for one or two of the
-//! instructions.
+//! MSP430's instructions.
 
 use super::*;
 

src/parser/instruction/encoding/jump_target.rs

@@ -1,9 +1,11 @@
 // © 2023 John Breaux
-//! A [JumpTarget] contains the [pc-relative offset](Number) or [Identifier]
+//! A [JumpTarget] contains the [pc-relative offset](Number) or [label](Identifier)
-//! for a [Jump instruction encoding](Encoding::Jump)
+//! for a [Jump](Encoding::Jump) [instruction]
 use super::*;
 
-/// The target of a [Jump](Encoding::Jump)
+/// Contains the [pc-relative offset](Number) or [label](Identifier)
+/// for a [Jump](Encoding::Jump) [instruction]
+// TODO: Allow identifiers in JumpTarget
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct JumpTarget(Number);
 

src/parser/instruction/encoding/primary_operand.rs

@@ -1,10 +1,10 @@
 // © 2023 John Breaux
 //! A [PrimaryOperand] contains the first [Register], addressing mode, and Extension
-//! Word for an [instruction](Instruction)
+//! Word for a [one-operand](Encoding::Single) or [two-operand](Encoding::Double) [instruction]
 use super::*;
 
-/// The Source of a [Double](Encoding::Double) or Destination of a
+/// Contains the first [Register], addressing mode, and Extension Word for a
-/// [Single](Encoding::Single)
+/// [one-operand](Encoding::Single) or [two-operand](Encoding::Double) [instruction]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum PrimaryOperand {
     Direct(Register),

src/parser/instruction/encoding/secondary_operand.rs

@@ -1,6 +1,6 @@
 // © 2023 John Breaux
 //! A [SecondaryOperand] contains the second [Register], addressing mode, and Extension
-//! Word for a [two-operand](Encoding::Double) [instruction](Instruction)
+//! Word for a [two-operand](Encoding::Double) [instruction]
 use super::*;
 
 /// The destination of a [Double](Encoding::Double)
@@ -41,16 +41,16 @@ impl SecondaryOperand {
 }
 
 impl Parsable for SecondaryOperand {
-    /// Separator
+    // Separator
-    /// - Register  => Direct
+    // - Register  => Direct
-    /// - Number    => Indexed
+    // - Number    => Indexed
-    ///     - OpenIdx
+    //     - OpenIdx
-    ///         - Register
+    //         - Register
-    ///             - CloseIdx
+    //             - CloseIdx
-    /// - Absolute
+    // - Absolute
-    ///   - Number
+    //   - Number
-    /// - Immediate
+    // - Immediate
-    ///   - Number == 0, 1
+    //   - Number == 0, 1
     fn parse<'text, T>(p: &Parser, stream: &mut T) -> Result<Self, crate::Error>
     where T: crate::TokenStream<'text> {
         use SecondaryOperand::*;

src/parser/instruction/encoding/width.rs

@@ -1,4 +1,5 @@
 // © 2023 John Breaux
+//! A [Width] represents whether an instruction operates on whole words or bytes
 use super::*;
 
 /// Represents an instruction's operand width.