From b9c35c0e68a8312d9fa3127c75c1c2f05e05859b Mon Sep 17 00:00:00 2001
From: John Breaux <j@soft.fish>
Date: Wed, 29 Mar 2023 23:45:39 -0500
Subject: [PATCH] lib.rs: Deny (missing docs)

---
 src/bus.rs             |  3 ++-
 src/cpu.rs             | 11 +++++++++++
 src/cpu/disassemble.rs | 14 +++++++++++---
 src/error.rs           |  8 ++++++++
 src/io.rs              |  4 ++--
 src/lib.rs             | 17 ++++++++++-------
 6 files changed, 44 insertions(+), 13 deletions(-)

diff --git a/src/bus.rs b/src/bus.rs
index c8bea42..b9eb5ff 100644
--- a/src/bus.rs
+++ b/src/bus.rs
@@ -59,6 +59,7 @@ pub enum Region {
     Screen,
     /// Stack space
     Stack,
+    #[doc(hidden)]
     /// Total number of named regions
     Count,
 }
@@ -293,7 +294,7 @@ impl Bus {
     ///#    Ok(())
     ///# }
     /// ```
-    /// If there is no Screen region, it will return Err(Error::MissingRegion)
+    /// If there is no Screen region, it will return Err([MissingRegion])
     /// ```rust,should_panic
     ///# use chirp::prelude::*;
     ///# fn main() -> Result<()> {
diff --git a/src/cpu.rs b/src/cpu.rs
index 0cbf1fe..85a6b75 100644
--- a/src/cpu.rs
+++ b/src/cpu.rs
@@ -61,14 +61,22 @@ impl Default for Quirks {
     }
 }
 
+/// Represents flags that aid in operation, but aren't inherent to the CPU
 #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ControlFlags {
+    /// Set when debug (live disassembly) mode enabled
     pub debug: bool,
+    /// Set when the emulator is paused by the user and should not update
     pub pause: bool,
+    /// Set when the emulator is waiting for a keypress
     pub keypause: bool,
+    /// Set when the emulator is waiting for a frame to be drawn
     pub vbi_wait: bool,
+    /// Set to the last key that's been *released* after a keypause
     pub lastkey: Option<usize>,
+    /// Represents the set of emulator "[Quirks]" to enable
     pub quirks: Quirks,
+    /// Represents the number of instructions to run per tick of the internal timer
     pub monotonic: Option<usize>,
 }
 
@@ -111,6 +119,8 @@ impl ControlFlags {
 /// Represents the internal state of the CPU interpreter
 #[derive(Clone, Debug, PartialEq)]
 pub struct CPU {
+    /// Flags that control how the CPU behaves, but which aren't inherent to the
+    /// implementation. Includes [Quirks], target IPF, etc.
     pub flags: ControlFlags,
     // memory map info
     screen: Adr,
@@ -468,6 +478,7 @@ impl CPU {
             return self;
         };
 
+        // Convert the elapsed time to 60ths of a second
         let time = self.timer.elapsed().as_secs_f64() * 60.0;
         self.timer = Instant::now();
         if time > 1.0 {
diff --git a/src/cpu/disassemble.rs b/src/cpu/disassemble.rs
index ec5c336..9014b96 100644
--- a/src/cpu/disassemble.rs
+++ b/src/cpu/disassemble.rs
@@ -7,31 +7,38 @@ use super::{Adr, Nib, Reg};
 use owo_colors::{OwoColorize, Style};
 type Ins = Nib;
 
+/// Extracts the I nibble of an IXYN instruction
 #[inline]
 pub fn i(ins: u16) -> Ins {
     (ins >> 12 & 0xf) as Ins
 }
+/// Extracts the X nibble of an IXYN instruction
 #[inline]
 pub fn x(ins: u16) -> Reg {
     (ins >> 8 & 0xf) as Reg
 }
+/// Extracts the Y nibble of an IXYN instruction
 #[inline]
 pub fn y(ins: u16) -> Reg {
     (ins >> 4 & 0xf) as Reg
 }
+/// Extracts the N nibble of an IXYN instruction
 #[inline]
 pub fn n(ins: u16) -> Nib {
     (ins & 0xf) as Nib
 }
+/// Extracts the B byte of an IXBB instruction
 #[inline]
 pub fn b(ins: u16) -> u8 {
     (ins & 0xff) as u8
 }
+/// Extracts the ADR trinibble of an IADR instruction
 #[inline]
 pub fn a(ins: u16) -> Adr {
     ins & 0x0fff
 }
 
+/// Disassembles Chip-8 instructions, printing them in the provided [owo_colors::Style]s
 #[derive(Clone, Debug, PartialEq)]
 pub struct Disassemble {
     invalid: Style,
@@ -46,15 +53,15 @@ impl Default for Disassemble {
 
 // Public API
 impl Disassemble {
-    // Returns a new Disassemble with the provided Styles
+    /// Returns a new Disassemble with the provided Styles
     pub fn new(invalid: Style, normal: Style) -> Disassemble {
         Disassemble { invalid, normal }
     }
-    //
+    /// Creates a [DisassembleBuilder], for partial configuration
     pub fn builder() -> DisassembleBuilder {
         DisassembleBuilder::default()
     }
-    // Disassemble a single instruction
+    /// Disassemble a single instruction
     pub fn instruction(&self, opcode: u16) -> String {
         let (i, x, y, n, b, a) = (
             i(opcode),
@@ -374,6 +381,7 @@ impl Disassemble {
     }
 }
 
+/// Builder for [Disassemble]rs
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct DisassembleBuilder {
     invalid: Option<Style>,
diff --git a/src/error.rs b/src/error.rs
index c526107..f1edac8 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -6,20 +6,28 @@
 use crate::bus::Region;
 use thiserror::Error;
 
+/// Result type, equivalent to [std::result::Result]<T, [enum@Error]>
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// Error type for Chirp.
 #[derive(Debug, Error)]
 pub enum Error {
+    /// Represents an unimplemented operation
     #[error("Unrecognized opcode {word}")]
     UnimplementedInstruction {
+        /// The offending word
         word: u16,
     },
+    /// The region you asked for was not defined
     #[error("No {region} found on bus")]
     MissingRegion {
+        /// The offending [Region]
         region: Region,
     },
+    /// Error originated in [std::io]
     #[error(transparent)]
     IoError(#[from] std::io::Error),
+    /// Error originated in [minifb]
     #[error(transparent)]
     MinifbError(#[from] minifb::Error),
 }
diff --git a/src/io.rs b/src/io.rs
index c1c17c7..9940248 100644
--- a/src/io.rs
+++ b/src/io.rs
@@ -1,8 +1,8 @@
 // (c) 2023 John A. Breaux
 // This code is licensed under MIT license (see LICENSE.txt for details)
-
+#![allow(missing_docs)]
 //! Platform-specific IO/UI code, and some debug functionality.
-//! TODO: Break this into its own crate.
+//! TODO: Destroy this all.
 
 use std::{
     ffi::OsStr,
diff --git a/src/lib.rs b/src/lib.rs
index cd3b4b3..f2cd5f3 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,7 @@
 // (c) 2023 John A. Breaux
 // This code is licensed under MIT license (see LICENSE.txt for details)
-
 #![cfg_attr(feature = "unstable", feature(no_coverage))]
+#![deny(missing_docs)]
 //! This crate implements a Chip-8 interpreter as if it were a real CPU architecture,
 //! to the best of my current knowledge. As it's the first emulator project I've
 //! embarked on, and I'm fairly new to Rust, it's going to be rough around the edges.
@@ -13,12 +13,6 @@ pub mod cpu;
 pub mod error;
 pub mod io;
 
-#[derive(Clone, Debug, Default, PartialEq)]
-pub struct Chip8 {
-    pub cpu: cpu::CPU,
-    pub bus: bus::Bus,
-}
-
 /// Common imports for Chirp
 pub mod prelude {
     pub use super::Chip8;
@@ -29,3 +23,12 @@ pub mod prelude {
     pub use error::Result;
     pub use io::{UIBuilder, *};
 }
+
+/// Holds the state of a Chip-8
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct Chip8 {
+    /// Contains the registers, flags, and operating state for a single Chip-8
+    pub cpu: cpu::CPU,
+    /// Contains the memory of a chip-8
+    pub bus: bus::Bus,
+}