j/Chirp
1
1
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

docs: Fix examples (now passes all doc tests again)

Browse Source
This commit is contained in:
John 2023-08-31 22:39:14 -05:00
parent 31c904f89c
commit 8de4f42ff6
4 changed files with 29 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/cpu.rs
View File

@ -399,9 +399,7 @@ impl CPU {
/// ```rust
/// # use chirp::*;
/// let mut cpu = CPU::default();
/// let mut screen = mem!{
/// Screen [0x000..0x100],
/// };
/// let mut screen = Screen::default();
/// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]);
/// cpu.singlestep(&mut screen).unwrap();
/// assert_eq!(0x202, cpu.pc());
@ -422,9 +420,7 @@ impl CPU {
/// ```rust
/// # use chirp::*;
/// let mut cpu = CPU::default();
/// let mut screen = mem!{
/// Screen [0x000..0x100],
/// };
/// let mut screen = Screen::default();
/// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]);
/// cpu.multistep(&mut screen, 0x20)
/// .expect("The program should only have valid opcodes.");
@ -453,11 +449,9 @@ impl CPU {
/// ```rust
/// # use chirp::*;
/// let mut cpu = CPU::default();
/// let mut bus = mem!{
/// Screen [0x000..0x100],
/// };
/// let mut screen = Screen::default();
/// cpu.load_program_bytes(&[0x00, 0xe0, 0x22, 0x02]);
/// cpu.tick(&mut bus)
/// cpu.tick(&mut screen)
/// .expect("0x00e0 (cls) should be a valid opcode.");
/// assert_eq!(0x202, cpu.pc());
/// assert_eq!(1, cpu.cycle());
@ -470,9 +464,7 @@ impl CPU {
/// let mut cpu = CPU::default();
/// # cpu.flags.debug = true; // enable live disassembly
/// # cpu.flags.monotonic = true; // enable monotonic/test timing
/// let mut bus = mem!{
/// Screen [0x0f00..0x1000],
/// };
/// let mut bus = Screen::default();
/// cpu.load_program_bytes(&[
/// 0xff, 0xff, // invalid!
/// 0x22, 0x02, // jump 0x202

32
src/cpu/mem.rs
View File

@ -15,7 +15,7 @@ use std::{
/// Creates a new [Mem], growing as needed
/// # Examples
/// ```rust
/// # use chirp::*;
/// use chirp::{cpu::mem::Region::*, *};
/// let mut mem = mem! {
/// Charset [0x0000..0x0800] = b"ABCDEF",
/// Program [0x0800..0xf000] = include_bytes!("mem.rs"),
@ -33,7 +33,7 @@ impl Grab for Mem {
/// Gets a slice of [Mem] memory
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new()
/// .add_region_owned(Program, 0..10);
@ -52,7 +52,7 @@ impl Grab for Mem {
/// Gets a mutable slice of [Mem] memory
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mut mem = Mem::new()
/// .add_region_owned(Program, 0..10);
@ -112,7 +112,7 @@ impl Mem {
/// Constructs a new mem
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new();
/// assert!(mem.is_empty());
@ -126,7 +126,7 @@ impl Mem {
/// Gets the length of the mem' backing memory
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234);
@ -141,7 +141,7 @@ impl Mem {
/// Returns true if the backing memory contains no elements
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new();
/// assert!(mem.is_empty());
@ -155,7 +155,7 @@ impl Mem {
/// Grows the Mem backing memory to at least size bytes, but does not truncate
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mut mem = Mem::new();
/// mem.with_size(1234);
@ -165,7 +165,7 @@ impl Mem {
///# Ok(())
///# }
/// ```
fn with_size(&mut self, size: usize) {
pub fn with_size(&mut self, size: usize) {
if self.len() < size {
self.memory.resize(size, 0);
}
@ -180,7 +180,7 @@ impl Mem {
/// Adds a new named range ([Region]) to a [Mem]
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mut mem = Mem::new();
/// mem.add_region(Program, 0..1234);
@ -199,7 +199,7 @@ impl Mem {
/// Updates an existing [Region]
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mut mem = Mem::new().add_region_owned(Program, 0..1234);
/// mem.set_region(Program, 1234..2345);
@ -224,7 +224,7 @@ impl Mem {
/// Loads data into a named [Region]
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234)
@ -244,7 +244,7 @@ impl Mem {
/// Fills a [Region] with zeroes
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234)
@ -255,11 +255,11 @@ impl Mem {
/// ```
/// If the region doesn't exist, that's okay.
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new()
/// .add_region_owned(Program, 0..1234)
/// .clear_region(Screen);
/// .clear_region(Program);
///# // TODO: test if region actually clear
///# Ok(())
///# }
@ -274,7 +274,7 @@ impl Mem {
/// Gets a slice of a named [Region] of memory
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mem = Mem::new()
/// .add_region_owned(Program, 0..10);
@ -291,7 +291,7 @@ impl Mem {
/// Gets a mutable slice of a named region of memory
/// # Examples
/// ```rust
///# use chirp::*;
/// use chirp::{cpu::mem::{Region::*, Mem}, *};
///# fn main() -> Result<()> {
/// let mut mem = Mem::new()
/// .add_region_owned(Program, 0..10);

4
src/screen.rs
View File

@ -72,9 +72,9 @@ impl Screen {
/// ```rust
///# use chirp::screen::Screen;
/// let mut screen = Screen::new(256);
/// assert_eq!(1234, screen.len());
/// assert_eq!(256, screen.len());
/// screen.with_size(0);
/// assert_eq!(1234, screen.len());
/// assert_eq!(256, screen.len());
/// ```
pub fn with_size(&mut self, size: usize) {
if self.len() < size {

12
src/traits/auto_cast.rs
View File

@ -31,11 +31,11 @@ pub trait AutoCast<T>: FallibleAutoCast<T> {
///
/// # May Panic
///
/// If the type is not [Default], this will panic on error.
/// This will panic on error. For a non-panicking implementation, do it yourself.
fn read(&self, addr: impl Into<usize>) -> T {
self.read_fallible(addr).unwrap_or_else(|e| panic!("{e:?}"))
}
/// Write a T to address `addr`
/// Writes a T to address `addr`
///
/// # Will Panic
///
@ -63,7 +63,7 @@ pub trait FallibleAutoCast<T>: Grab {
/// - `Self::to_be_bytes`
macro_rules! impl_rw {($($t:ty) ,* $(,)?) =>{
$(
#[doc = concat!("Read or Write [", stringify!($t), "] at address `addr`, *discarding errors*.\n\nThis will never panic.")]
#[doc = concat!("Read or Write [`", stringify!($t), "`] at address `addr`, *discarding errors*.\n\nThis will never panic.")]
impl<T: Grab + FallibleAutoCast<$t>> AutoCast<$t> for T {
#[inline(always)]
fn read(&self, addr: impl Into<usize>) -> $t {
@ -79,12 +79,12 @@ macro_rules! impl_rw {($($t:ty) ,* $(,)?) =>{
#[inline(always)]
fn read_fallible(&self, addr: impl Into<usize>) -> $crate::error::Result<$t> {
let addr: usize = addr.into();
let range = addr..addr + core::mem::size_of::<$t>();
if let Some(bytes) = self.grab(range.clone()) {
let top = addr + core::mem::size_of::<$t>();
if let Some(bytes) = self.grab(addr..top) {
// Chip-8 is a big-endian system
Ok(<$t>::from_be_bytes(bytes.try_into()?))
} else {
Err($crate::error::Error::InvalidAddressRange{range: range.into()})
Err($crate::error::Error::InvalidAddressRange{range: (addr..top).into()})
}
}
#[inline(always)]