From 66863aad1ef6ffbaa4e2b9364399d14bdf197538 Mon Sep 17 00:00:00 2001 From: G2-Games Date: Wed, 19 Jun 2024 16:31:27 -0500 Subject: [PATCH] Improved docs --- src/lib.rs | 33 ++++++++++++++++++++++++++++++--- src/netmd/commands.rs | 25 +++++++++++++++++++++++++ src/netmd/interface.rs | 8 ++++---- src/netmd/mod.rs | 7 ++----- 4 files changed, 61 insertions(+), 12 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 1c64b5c..5923f4b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,31 @@ -/// A crate for controlling NetMD and Hi-MD devices. -/// -/// To use this library, first you need to get a device from [cross-usb] and then open [netmd::interface::NetMDInterface] +//! A crate for controlling NetMD and Hi-MD devices. +//! +//! This crate is entirely `async` (a necessity because of USB in WASM), but +//! it can be used in programs which are not async by using a crate like +//! [futures_lite](https://docs.rs/futures-lite/) with the `block_on` function. +//! +//! To use this library, first you need to get a device from [`cross_usb`] and +//! then open a [`NetMDContext`]. +//! +//! ```rust +//! use cross_usb::prelude::get_device; +//! use minidisc::netmd::base::DEVICE_IDS_CROSSUSB; +//! use minidisc::NetMDContext; +//! +//! // Get a device using the built-in list of descriptors for minidisc devices +//! let dev_descriptor = cross_usb::get_device(DEVICE_IDS_CROSSUSB).await +//! .expect("Failed to find device"); +//! +//! // Open a NetMD Context with the device +//! let context = NetMDContext::new(dev_descriptor).await +//! .expect("Could not create context"); +//! +//! // Perform operations on it ... +//! context.list_content().await +//! .expect("Could not list disc contents"); +//! ``` + pub mod netmd; + +#[doc(inline)] +pub use netmd::commands::NetMDContext; diff --git a/src/netmd/commands.rs b/src/netmd/commands.rs index 0082115..f045a4c 100644 --- a/src/netmd/commands.rs +++ b/src/netmd/commands.rs @@ -18,6 +18,7 @@ use super::utils::{ sanitize_full_width_title, sanitize_half_width_title, }; +/// The current reported status from the device. #[derive(Debug, Clone, Copy, FromPrimitive, PartialEq, Eq)] pub enum OperatingStatus { Ready = 50687, @@ -31,6 +32,7 @@ pub enum OperatingStatus { ReadyForTransfer = 65319, } +/// A representation of time in the same way NetMD devices do. #[derive(Debug, Clone)] pub struct Time { pub minute: u16, @@ -38,6 +40,7 @@ pub struct Time { pub frame: u16, } +/// A representation of the current status of the device. #[derive(Debug, Clone)] pub struct DeviceStatus { pub disc_present: bool, @@ -46,6 +49,7 @@ pub struct DeviceStatus { pub time: Time, } +/// Information about a single track #[derive(Debug, Clone)] pub struct Track { index: u16, @@ -58,6 +62,7 @@ pub struct Track { } impl Track { + /// Get the number of title cells a title will take up. pub fn cells_for_title(&self) -> (usize, usize) { let encoding_name_correction = match self.encoding { Encoding::SP => 0, @@ -74,6 +79,7 @@ impl Track { } } +/// Information about a single group on the disc, containing [`Track`]s #[derive(Debug, Clone)] pub struct Group { index: u16, @@ -82,6 +88,7 @@ pub struct Group { tracks: Vec, } +/// Information about a MiniDisc complete with [`Track`]s, [`Group`]s, and metadata. #[derive(Debug, Clone)] pub struct Disc { title: String, @@ -260,6 +267,11 @@ impl Disc { } } +/// Context for interacting with a NetMD device as a wrapper around a [`NetMDInterface`]. +/// +/// This struct wraps a [`NetMDInterface`] and allows for some higher level +/// functions, but it is still necessary to interact with the [`NetMDInterface`] +/// when performing many operations. pub struct NetMDContext { interface: NetMDInterface, } @@ -287,6 +299,7 @@ impl NetMDContext { self.interface.track_change(Direction::Restart).await } + /// Get the current status of the device pub async fn device_status(&mut self) -> Result> { let status = self.interface.status().await?; let playback_status = self.interface.playback_status2().await?; @@ -317,6 +330,7 @@ impl NetMDContext { }) } + /// Get a representation of the current disc inserted in the device. pub async fn list_content(&mut self) -> Result> { let flags = self.interface.disc_flags().await?; let title = self.interface.disc_title(false).await?; @@ -392,6 +406,7 @@ impl NetMDContext { Ok(()) } + /// Rename a disc while preserving group titles pub async fn rename_disc( &mut self, new_name: &str, @@ -471,6 +486,7 @@ impl NetMDContext { Ok(()) } + /// Get a track from the device. This only works with MZ-RH1 devices. pub async fn upload( &mut self, track: u16, @@ -524,6 +540,9 @@ impl NetMDContext { Ok(()) } + /// Start downloading an [`MDTrack`] to the device. + /// + /// Progress is updated in the `progress_callback` closure. pub async fn download( &mut self, track: MDTrack, @@ -545,16 +564,22 @@ impl NetMDContext { Ok(result) } + /// Get a reference to the underlying interface. + /// + /// [`NetMDContext::interface_mut()`] is almost certainly more useful + /// in most cases. pub fn interface(&self) -> &NetMDInterface { &self.interface } + /// Get a mutable reference to the underlying interface. pub fn interface_mut(&mut self) -> &mut NetMDInterface { &mut self.interface } } impl From for NetMDContext { + /// Create a context from an already opened interface. fn from(value: NetMDInterface) -> Self { Self { interface: value } } diff --git a/src/netmd/interface.rs b/src/netmd/interface.rs index 06975ac..140d301 100644 --- a/src/netmd/interface.rs +++ b/src/netmd/interface.rs @@ -1705,7 +1705,7 @@ impl NetMDInterface { // Sharps are slow cross_sleep(Duration::from_millis(200)).await; - let mut _written_bytes = 0; + let mut written_bytes = 0; let mut packet_count = 0; while let Some((key, iv, data)) = packets.recv().await { @@ -1716,10 +1716,10 @@ impl NetMDInterface { data }; self.device.write_bulk(&binpack).await?; - _written_bytes += binpack.len(); + written_bytes += binpack.len(); packet_count += 1; - (progress_callback)(total_bytes, _written_bytes); - if total_bytes == _written_bytes { + (progress_callback)(total_bytes, written_bytes); + if total_bytes == written_bytes { packets.close(); break; } diff --git a/src/netmd/mod.rs b/src/netmd/mod.rs index 8e8a42f..8d25966 100644 --- a/src/netmd/mod.rs +++ b/src/netmd/mod.rs @@ -1,8 +1,5 @@ -/*! - * This crate is an interface in rust to control NetMD and Hi-MD minidisc devices. - * - * Documentation coming soon - */ +//! This module contains all functionality for interacting with NetMD minidisc +//! devices. pub mod base; pub mod commands;