From 30c3fb058522fb9dc8544bfed9ceffd4bf83ee63 Mon Sep 17 00:00:00 2001 From: Andrea Ciliberti Date: Sat, 22 Jul 2023 16:41:42 +0200 Subject: [PATCH] Small example fmt --- ctru-rs/src/applets/mii_selector.rs | 7 +++++ ctru-rs/src/applets/swkbd.rs | 9 ++++++ ctru-rs/src/services/am.rs | 3 ++ ctru-rs/src/services/apt.rs | 43 +++++++++++++++++++++++++++-- ctru-rs/src/services/cam.rs | 6 ++-- ctru-rs/src/services/cfgu.rs | 4 +-- ctru-rs/src/services/fs.rs | 4 +-- ctru-rs/src/services/gfx.rs | 10 +++---- ctru-rs/src/services/hid.rs | 4 +-- ctru-rs/src/services/ps.rs | 4 ++- ctru-rs/src/services/romfs.rs | 4 +-- ctru-rs/src/services/soc.rs | 8 +++--- ctru-rs/src/services/sslc.rs | 4 +-- 13 files changed, 84 insertions(+), 26 deletions(-) diff --git a/ctru-rs/src/applets/mii_selector.rs b/ctru-rs/src/applets/mii_selector.rs index 16e885c..0562777 100644 --- a/ctru-rs/src/applets/mii_selector.rs +++ b/ctru-rs/src/applets/mii_selector.rs @@ -96,6 +96,7 @@ impl MiiSelector { /// This function will panic if the given `&str` contains NUL bytes. /// /// # Example + /// /// ```no_run /// # fn main() { /// use ctru::applets::mii_selector::MiiSelector; @@ -119,6 +120,7 @@ impl MiiSelector { /// This will overwrite any previously saved options. Use bitwise operations to set all your wanted options at once. /// /// # Example + /// /// ```no_run /// # fn main() { /// use ctru::applets::mii_selector::{MiiSelector, Options}; @@ -142,6 +144,7 @@ impl MiiSelector { /// Look into [`MiiSelector::set_options()`] to see how to work with options. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -170,6 +173,7 @@ impl MiiSelector { /// Look into [`MiiSelector::set_options()`] to see how to work with options. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -193,6 +197,7 @@ impl MiiSelector { /// Whitelist a user-created Mii based on its index. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -216,6 +221,7 @@ impl MiiSelector { /// Blacklist a user-created Mii based on its index. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -253,6 +259,7 @@ impl MiiSelector { /// TODO: UNSAFE OPERATION, LAUNCHING APPLETS REQUIRES GRAPHICS, WITHOUT AN ACTIVE GFX THIS WILL CAUSE A SEGMENTATION FAULT. /// /// # Example + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { diff --git a/ctru-rs/src/applets/swkbd.rs b/ctru-rs/src/applets/swkbd.rs index b399fb0..879c434 100644 --- a/ctru-rs/src/applets/swkbd.rs +++ b/ctru-rs/src/applets/swkbd.rs @@ -158,6 +158,7 @@ impl SoftwareKeyboard { /// Initialize a new configuration for the Software Keyboard applet depending on how many "exit" buttons are available to the user (1, 2 or 3). /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -188,6 +189,7 @@ impl SoftwareKeyboard { /// TODO: UNSAFE OPERATION, LAUNCHING APPLETS REQUIRES GRAPHICS, WITHOUT AN ACTIVE GFX THIS WILL CAUSE A SEGMENTATION FAULT. /// /// # Example + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { @@ -231,6 +233,7 @@ impl SoftwareKeyboard { /// TODO: UNSAFE OPERATION, LAUNCHING APPLETS REQUIRES GRAPHICS, WITHOUT AN ACTIVE GFX THIS WILL CAUSE A SEGMENTATION FAULT. /// /// # Example + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { @@ -261,6 +264,7 @@ impl SoftwareKeyboard { /// Set special features for this keyboard. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -280,6 +284,7 @@ impl SoftwareKeyboard { /// Configure input validation for this keyboard. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -302,6 +307,7 @@ impl SoftwareKeyboard { /// Configure the maximum number of digits that can be entered in the keyboard when the [`Filters::DIGITS`] flag is enabled. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -328,6 +334,7 @@ impl SoftwareKeyboard { /// The hint text is the text shown in gray before any text gets written in the input box. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -354,6 +361,7 @@ impl SoftwareKeyboard { /// - `submit` - whether pressing the button will accept the keyboard's input or discard it. /// /// # Example + /// /// ```no_run /// # fn main() { /// # @@ -392,6 +400,7 @@ impl SoftwareKeyboard { /// receivable by [`SoftwareKeyboard::get_string()`] and [`SoftwareKeyboard::write_exact()`]. /// /// # Example + /// /// ```no_run /// # fn main() { /// # diff --git a/ctru-rs/src/services/am.rs b/ctru-rs/src/services/am.rs index d570529..d302448 100644 --- a/ctru-rs/src/services/am.rs +++ b/ctru-rs/src/services/am.rs @@ -58,6 +58,7 @@ impl Am { /// Initialize a new service handle. /// /// # Example + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { @@ -80,6 +81,7 @@ impl Am { /// Returns the amount of titles currently installed in a specific install location. /// /// # Example + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { @@ -108,6 +110,7 @@ impl Am { /// Returns the list of titles installed in a specific install location. /// /// # Example + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { diff --git a/ctru-rs/src/services/apt.rs b/ctru-rs/src/services/apt.rs index 0f5eb25..e885adf 100644 --- a/ctru-rs/src/services/apt.rs +++ b/ctru-rs/src/services/apt.rs @@ -1,8 +1,10 @@ //! Applet service. //! -//! The APT service handles integration with some higher level OS features such as Sleep mode, the Home Menu and application switching. +//! The APT service handles integration with other applications, +//! including high-level OS features such as Sleep mode, the Home Menu and application switching. //! -//! It also handles running applets, small programs made available by the OS to streamline specific functionality. Those are implemented in the [`applets`](crate::applets) module. +//! It also handles running applets, small programs made available by the OS to streamline specific functionality. +//! Those are implemented in the [`applets`](crate::applets) module. use crate::error::ResultCode; @@ -10,7 +12,21 @@ use crate::error::ResultCode; pub struct Apt(()); impl Apt { - /// Initialize a new handle. + /// Initialize a new service handle. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::apt::Apt; + /// + /// let apt = Apt::new()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "aptInit")] pub fn new() -> crate::Result { unsafe { @@ -25,6 +41,27 @@ impl Apt { /// /// This function is called as such since it automatically handles all checks for Home Menu switching, Sleep mode and other events that could take away control from the application. /// For this reason, its main use is as the condition of a while loop that controls the main logic for your program. + /// + /// # Example + /// + /// ```no_run + /// use std::error::Error; + /// use ctru::services::apt::Apt; + /// + /// // In a simple `main` function, the structure should be the following. + /// fn main() -> Result<(), Box> { + /// + /// let apt = Apt::new()?; + /// + /// while apt.main_loop() { + /// // Main program logic should be written here. + /// } + /// + /// // Optional clean-ups after running the application should be written after the main loop. + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "aptMainLoop")] pub fn main_loop(&self) -> bool { unsafe { ctru_sys::aptMainLoop() } diff --git a/ctru-rs/src/services/cam.rs b/ctru-rs/src/services/cam.rs index de9ecb5..717694e 100644 --- a/ctru-rs/src/services/cam.rs +++ b/ctru-rs/src/services/cam.rs @@ -1,6 +1,6 @@ -//! Camera service +//! Camera service. //! -//! The CAM service provides access to the cameras. Cameras can return images +//! The CAM service provides access to the built-in cameras. [`Camera`]s can return images //! in the form of byte vectors which can be displayed or used in other ways. use crate::error::{Error, ResultCode}; @@ -856,7 +856,7 @@ pub trait Camera { } impl Cam { - /// Initializes the CAM service. + /// Initialize a new service handle. /// /// # Errors /// diff --git a/ctru-rs/src/services/cfgu.rs b/ctru-rs/src/services/cfgu.rs index 99ef505..9afbe7b 100644 --- a/ctru-rs/src/services/cfgu.rs +++ b/ctru-rs/src/services/cfgu.rs @@ -1,4 +1,4 @@ -//! Configuration service +//! System Configuration service. //! //! This module contains basic methods to retrieve and change configuration from the console. @@ -82,7 +82,7 @@ pub enum SystemModel { pub struct Cfgu(()); impl Cfgu { - /// Initializes the CFGU service. + /// Initialize a new service handle. /// /// # Errors /// diff --git a/ctru-rs/src/services/fs.rs b/ctru-rs/src/services/fs.rs index 1f0fed7..446be7e 100644 --- a/ctru-rs/src/services/fs.rs +++ b/ctru-rs/src/services/fs.rs @@ -1,4 +1,4 @@ -//! Filesystem service +//! FileSystem service. //! //! This module contains basic methods to manipulate the contents of the 3DS's filesystem. //! Only the SD card is currently supported. You should prefer using `std::fs`. @@ -320,7 +320,7 @@ unsafe impl Send for Dir {} unsafe impl Sync for Dir {} impl Fs { - /// Initializes the FS service. + /// Initialize a new service handle. /// /// # Errors /// diff --git a/ctru-rs/src/services/gfx.rs b/ctru-rs/src/services/gfx.rs index b1432f2..e6465e4 100644 --- a/ctru-rs/src/services/gfx.rs +++ b/ctru-rs/src/services/gfx.rs @@ -1,4 +1,4 @@ -//! LCD screens manipulation helper +//! Graphics service. use std::cell::{Ref, RefCell, RefMut}; use std::marker::PhantomData; @@ -219,7 +219,8 @@ pub struct Gfx { static GFX_ACTIVE: Mutex = Mutex::new(0); impl Gfx { - /// Creates a new [`Gfx`] instance with default init values + /// Initialize a new default service handle. + /// /// It's the same as calling: /// /// ```no_run @@ -239,10 +240,9 @@ impl Gfx { Gfx::with_formats(FramebufferFormat::Bgr8, FramebufferFormat::Bgr8, false) } - /// Initialize the Gfx module with the chosen framebuffer formats for the top and bottom - /// screens + /// Initialize a new service handle with the chosen framebuffer formats for the top and bottom screens. /// - /// Use `Gfx::new()` instead of this function to initialize the module with default parameters + /// Use [`Gfx::new()`] instead of this function to initialize the module with default parameters #[doc(alias = "gfxInit")] pub fn with_formats( top_fb_fmt: FramebufferFormat, diff --git a/ctru-rs/src/services/hid.rs b/ctru-rs/src/services/hid.rs index b592f6a..79bb6df 100644 --- a/ctru-rs/src/services/hid.rs +++ b/ctru-rs/src/services/hid.rs @@ -1,4 +1,4 @@ -//! HID service +//! Human-Interface Device service. //! //! The HID service provides access to user input such as button presses, touch screen presses, //! and circle pad information. It also provides information from the sound volume slider, @@ -79,7 +79,7 @@ bitflags! { pub struct Hid(()); impl Hid { - /// Initializes the HID service. + /// Initialize a new service handle. /// /// # Errors /// diff --git a/ctru-rs/src/services/ps.rs b/ctru-rs/src/services/ps.rs index 6f8c67c..fc108fd 100644 --- a/ctru-rs/src/services/ps.rs +++ b/ctru-rs/src/services/ps.rs @@ -1,4 +1,6 @@ -//! Process Services (PS) module. This is used for miscellaneous utility tasks, but +//! Process Services. +//! +//! This is used for miscellaneous utility tasks, but //! is particularly important because it is used to generate random data, which //! is required for common things like [`HashMap`](std::collections::HashMap). //! See also diff --git a/ctru-rs/src/services/romfs.rs b/ctru-rs/src/services/romfs.rs index c8719a2..c1c2d9e 100644 --- a/ctru-rs/src/services/romfs.rs +++ b/ctru-rs/src/services/romfs.rs @@ -1,4 +1,4 @@ -//! Read-Only Memory FileSystem +//! Read-Only Memory FileSystem service. //! //! This module only gets compiled if the configured RomFS directory is found and the `romfs` //! feature is enabled. @@ -31,7 +31,7 @@ pub struct RomFS { static ROMFS_ACTIVE: Mutex = Mutex::new(0); impl RomFS { - /// Mounts the specified RomFS folder as a virtual drive. + /// Mount the specified RomFS folder as a virtual drive. #[doc(alias = "romfsMountSelf")] pub fn new() -> crate::Result { let _service_handler = ServiceReference::new( diff --git a/ctru-rs/src/services/soc.rs b/ctru-rs/src/services/soc.rs index 2bbfe50..aa450be 100644 --- a/ctru-rs/src/services/soc.rs +++ b/ctru-rs/src/services/soc.rs @@ -1,4 +1,4 @@ -//! Network Socket +//! Network Socket service. use libc::memalign; use std::net::Ipv4Addr; @@ -20,11 +20,11 @@ pub struct Soc { static SOC_ACTIVE: Mutex = Mutex::new(0); impl Soc { - /// Initialize the Soc service with a default buffer size of 0x100000 bytes + /// Initialize a new service handle using a socket buffer size of 0x100000 bytes. /// /// # Errors /// - /// This function will return an error if the `Soc` service is already initialized + /// This function will return an error if the [`Soc`] service is already initialized #[doc(alias = "socInit")] pub fn new() -> crate::Result { Self::init_with_buffer_size(0x100000) @@ -35,7 +35,7 @@ impl Soc { /// /// # Errors /// - /// This function will return an error if the `Soc` service is already initialized + /// This function will return an error if the [`Soc`] service is already initialized #[doc(alias = "socInit")] pub fn init_with_buffer_size(num_bytes: usize) -> crate::Result { let _service_handler = ServiceReference::new( diff --git a/ctru-rs/src/services/sslc.rs b/ctru-rs/src/services/sslc.rs index 9b311e3..b13fac0 100644 --- a/ctru-rs/src/services/sslc.rs +++ b/ctru-rs/src/services/sslc.rs @@ -1,4 +1,4 @@ -//! SSLC (TLS) service +//! SSLC (TLS) service. // TODO: Implement remaining functions @@ -8,7 +8,7 @@ use crate::error::ResultCode; pub struct SslC(()); impl SslC { - /// Initialize the service + /// Initialize a new service handle. #[doc(alias = "sslcInit")] pub fn new() -> crate::Result { unsafe {