From 4124df8612b8abcdb7ac481b0ace37ef541e644e Mon Sep 17 00:00:00 2001 From: Andrea Ciliberti Date: Sun, 9 Jul 2023 19:53:15 +0200 Subject: [PATCH] Fixed all compiler warnings for docs --- ctru-rs/src/applets/mii_selector.rs | 5 +++-- ctru-rs/src/applets/mod.rs | 5 +++++ ctru-rs/src/applets/swkbd.rs | 4 ++++ ctru-rs/src/console.rs | 16 ++++++++++++++++ ctru-rs/src/prelude.rs | 4 ++++ ctru-rs/src/services/gfx.rs | 2 ++ ctru-rs/src/services/hid.rs | 14 +++++++------- ctru-rs/src/services/ndsp/mod.rs | 19 ++++++++++++++++--- ctru-rs/src/services/ndsp/wave.rs | 2 ++ ctru-rs/src/services/ps.rs | 5 +++++ ctru-rs/src/services/romfs.rs | 7 +++++++ 11 files changed, 71 insertions(+), 12 deletions(-) diff --git a/ctru-rs/src/applets/mii_selector.rs b/ctru-rs/src/applets/mii_selector.rs index 577d0df..7cd0f81 100644 --- a/ctru-rs/src/applets/mii_selector.rs +++ b/ctru-rs/src/applets/mii_selector.rs @@ -1,6 +1,7 @@ -//! Mii Selector applet +//! Mii Selector applet. //! -//! This module contains the methods to launch the Mii Selector. +//! This applet opens a window on the console's bottom screen which lets the player/user choose a Mii from the ones present on their console. +//! The application can access the selected Mii's data via the use of the [`mii`](crate::mii) module. use crate::mii::MiiData; use bitflags::bitflags; diff --git a/ctru-rs/src/applets/mod.rs b/ctru-rs/src/applets/mod.rs index f5813ad..57c9471 100644 --- a/ctru-rs/src/applets/mod.rs +++ b/ctru-rs/src/applets/mod.rs @@ -1,2 +1,7 @@ +//! System Applets. +//! +//! Applets are small integrated programs that the OS makes available to the developer to streamline commonly needed functionality. +//! Thanks to these integrations the developer can avoid wasting time re-implementing common features and instead use a more reliable base for their application. + pub mod mii_selector; pub mod swkbd; diff --git a/ctru-rs/src/applets/swkbd.rs b/ctru-rs/src/applets/swkbd.rs index e5e9c28..d0f0fdf 100644 --- a/ctru-rs/src/applets/swkbd.rs +++ b/ctru-rs/src/applets/swkbd.rs @@ -1,3 +1,7 @@ +//! Software Keyboard applet. +//! +//! This applet opens a virtual keyboard on the console's bottom screen which lets the player/user write UTF-16 valid text. + use bitflags::bitflags; use ctru_sys::{ self, swkbdInit, swkbdInputText, swkbdSetButton, swkbdSetFeatures, swkbdSetHintText, SwkbdState, diff --git a/ctru-rs/src/console.rs b/ctru-rs/src/console.rs index cd6b51f..74b861e 100644 --- a/ctru-rs/src/console.rs +++ b/ctru-rs/src/console.rs @@ -1,3 +1,5 @@ +//! Virtual text console. + use std::cell::RefMut; use std::default::Default; @@ -7,6 +9,20 @@ use crate::services::gfx::Screen; static mut EMPTY_CONSOLE: PrintConsole = unsafe { const_zero::const_zero!(PrintConsole) }; +/// Virtual printable console. +/// +/// [`Console`] lets the application redirect `stdout` to a simple text displayer on the 3DS screen. +/// This means that any text written to `stdout` (e.g. using [`println!`] or [`dbg!`]) will become visible in the area taken by the console. +/// +/// # Notes +/// +/// The console will take full possession of the screen handed to it as long as it stays alive. It also supports ANSI codes. +/// +/// # Alternatives +/// +/// If you'd like to see live `stdout` output while running the application but can't/don't want to show the text on the 3DS itself, +/// you can try using [`Soc::redirect_to_3dslink`](crate::services::soc::Soc::redirect_to_3dslink) while activating the `--server` flag for `3dslink` (also supported by `cargo-3ds`). +/// More info in the `cargo-3ds` docs. #[doc(alias = "PrintConsole")] pub struct Console<'screen> { context: Box, diff --git a/ctru-rs/src/prelude.rs b/ctru-rs/src/prelude.rs index 49095fa..b765b65 100644 --- a/ctru-rs/src/prelude.rs +++ b/ctru-rs/src/prelude.rs @@ -1,3 +1,7 @@ +//! `use ctru::prelude::*;` to import common services, members and functions. +//! +//! Particularly useful when writing very small applications. + pub use crate::console::Console; pub use crate::services::{ apt::Apt, diff --git a/ctru-rs/src/services/gfx.rs b/ctru-rs/src/services/gfx.rs index 5629cf6..54ec061 100644 --- a/ctru-rs/src/services/gfx.rs +++ b/ctru-rs/src/services/gfx.rs @@ -209,7 +209,9 @@ pub enum Side { /// /// The service exits when this struct is dropped. pub struct Gfx { + /// Top screen representation. pub top_screen: RefCell, + /// Bottom screen representation. pub bottom_screen: RefCell, _service_handler: ServiceReference, } diff --git a/ctru-rs/src/services/hid.rs b/ctru-rs/src/services/hid.rs index 51bf63a..cb2550f 100644 --- a/ctru-rs/src/services/hid.rs +++ b/ctru-rs/src/services/hid.rs @@ -75,14 +75,14 @@ bitflags::bitflags! { /// This service requires no special permissions to use. pub struct Hid(()); -/// Initializes the HID service. -/// -/// # Errors -/// -/// This function will return an error if the service was unable to be initialized. -/// Since this service requires no special or elevated permissions, errors are -/// rare in practice. impl Hid { + /// Initializes the HID service. + /// + /// # Errors + /// + /// This function will return an error if the service was unable to be initialized. + /// Since this service requires no special or elevated permissions, errors are + /// rare in practice. #[doc(alias = "hidInit")] pub fn new() -> crate::Result { unsafe { diff --git a/ctru-rs/src/services/ndsp/mod.rs b/ctru-rs/src/services/ndsp/mod.rs index 2ff9d7b..e832551 100644 --- a/ctru-rs/src/services/ndsp/mod.rs +++ b/ctru-rs/src/services/ndsp/mod.rs @@ -1,4 +1,4 @@ -//! NDSP (Audio) service +//! NDSP (Audio) service. pub mod wave; use wave::{Wave, WaveStatus}; @@ -73,6 +73,19 @@ pub enum NdspError { SampleCountOutOfBounds(usize, usize), } +/// NDSP Channel representation. +/// +/// There are 24 individual channels in total and each can play a different audio [`Wave`] simultaneuosly. +/// +/// # Default +/// +/// NDSP initialises all channels with default values on creation, but the developer is supposed to change these values to correctly work with the service. +/// +/// In particular: +/// - Default audio format is set to [`AudioFormat::PCM16Mono`]. +/// - Default sample rate is set to 1 Hz. +/// - Default interpolation type is set to [`InterpolationType::Polyphase`]. +/// - Default mix is set to [`AudioMix::default()`] pub struct Channel<'ndsp> { id: u8, _rf: RefMut<'ndsp, ()>, // we don't need to hold any data @@ -169,7 +182,7 @@ impl Channel<'_> { unsafe { ctru_sys::ndspChnIsPaused(self.id.into()) } } - // Returns the channel's id + /// Returns the channel's index. pub fn id(&self) -> u8 { self.id } @@ -458,8 +471,8 @@ impl AudioMix { } } -/// Returns an [`AudioMix`] object with "front left" and "front right" volumes set to 100%, and all other volumes set to 0%. impl Default for AudioMix { + /// Returns an [`AudioMix`] object with "front left" and "front right" volumes set to 100%, and all other volumes set to 0%. fn default() -> Self { let mut mix = AudioMix::zeroed(); mix.set_front(1.0, 1.0); diff --git a/ctru-rs/src/services/ndsp/wave.rs b/ctru-rs/src/services/ndsp/wave.rs index 9194685..2819dbd 100644 --- a/ctru-rs/src/services/ndsp/wave.rs +++ b/ctru-rs/src/services/ndsp/wave.rs @@ -1,3 +1,5 @@ +//! Audio wave representation. + use super::{AudioFormat, NdspError}; use crate::linear::LinearAllocator; diff --git a/ctru-rs/src/services/ps.rs b/ctru-rs/src/services/ps.rs index 0673ce8..6f8c67c 100644 --- a/ctru-rs/src/services/ps.rs +++ b/ctru-rs/src/services/ps.rs @@ -52,9 +52,11 @@ pub enum AESKeyType { KeyslotInvalid = ctru_sys::PS_KEYSLOT_INVALID, } +/// Handle to the PS service. pub struct Ps(()); impl Ps { + /// Initialize a new service handle. #[doc(alias = "psInit")] pub fn new() -> Result { unsafe { @@ -63,6 +65,7 @@ impl Ps { } } + /// Returns the console's local friend code seed. #[doc(alias = "PS_GetLocalFriendCodeSeed")] pub fn local_friend_code_seed(&self) -> crate::Result { let mut seed: u64 = 0; @@ -71,6 +74,7 @@ impl Ps { Ok(seed) } + /// Returns the console's devide ID. #[doc(alias = "PS_GetDeviceId")] pub fn device_id(&self) -> crate::Result { let mut id: u32 = 0; @@ -79,6 +83,7 @@ impl Ps { Ok(id) } + /// Generates cryptografically secure random bytes and writes them into the `out` buffer. #[doc(alias = "PS_GenerateRandomBytes")] pub fn generate_random_bytes(&self, out: &mut [u8]) -> crate::Result<()> { ResultCode(unsafe { diff --git a/ctru-rs/src/services/romfs.rs b/ctru-rs/src/services/romfs.rs index 3c5afa8..dae4ed3 100644 --- a/ctru-rs/src/services/romfs.rs +++ b/ctru-rs/src/services/romfs.rs @@ -18,6 +18,12 @@ use std::sync::Mutex; use crate::services::ServiceReference; +/// Handle to the RomFS service. +/// +/// This service lets the application access a virtual mounted device created using a folder included within the application bundle. +/// `ctru` will include as RomFS the folder specified in the `Cargo.toml` manifest (or use `./romfs` by default). Look at the [`romfs`](self) module for more information. +/// +/// After mounting the RomFS file system, the included files and folders will be accessible exactly like any other file, just by using the drive prefix `romfs:/`. pub struct RomFS { _service_handler: ServiceReference, } @@ -25,6 +31,7 @@ pub struct RomFS { static ROMFS_ACTIVE: Mutex = Mutex::new(0); impl RomFS { + /// Mounts the specified RomFS folder as a virtual drive. #[doc(alias = "romfsMountSelf")] pub fn new() -> crate::Result { let _service_handler = ServiceReference::new(