diff --git a/ctru-rs/src/applets/mii_selector.rs b/ctru-rs/src/applets/mii_selector.rs index 0562777..76a4d5e 100644 --- a/ctru-rs/src/applets/mii_selector.rs +++ b/ctru-rs/src/applets/mii_selector.rs @@ -96,7 +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; @@ -120,7 +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}; @@ -144,7 +144,7 @@ impl MiiSelector { /// Look into [`MiiSelector::set_options()`] to see how to work with options. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -173,7 +173,7 @@ impl MiiSelector { /// Look into [`MiiSelector::set_options()`] to see how to work with options. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -197,7 +197,7 @@ impl MiiSelector { /// Whitelist a user-created Mii based on its index. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -221,7 +221,7 @@ impl MiiSelector { /// Blacklist a user-created Mii based on its index. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -259,7 +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 879c434..f20819b 100644 --- a/ctru-rs/src/applets/swkbd.rs +++ b/ctru-rs/src/applets/swkbd.rs @@ -158,7 +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() { /// # @@ -189,7 +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> { @@ -233,7 +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> { @@ -264,7 +264,7 @@ impl SoftwareKeyboard { /// Set special features for this keyboard. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -284,7 +284,7 @@ impl SoftwareKeyboard { /// Configure input validation for this keyboard. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -307,7 +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() { /// # @@ -334,7 +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() { /// # @@ -361,7 +361,7 @@ impl SoftwareKeyboard { /// - `submit` - whether pressing the button will accept the keyboard's input or discard it. /// /// # Example - /// + /// /// ```no_run /// # fn main() { /// # @@ -400,7 +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 d302448..e67282e 100644 --- a/ctru-rs/src/services/am.rs +++ b/ctru-rs/src/services/am.rs @@ -58,7 +58,7 @@ impl Am { /// Initialize a new service handle. /// /// # Example - /// + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { @@ -81,7 +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> { @@ -110,7 +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> { @@ -157,14 +157,12 @@ impl Am { Ok(info .into_iter() - .map(|title| { - Title { - id: title.titleID, - mediatype, - size: title.size, - version: title.version, - _am: PhantomData, - } + .map(|title| Title { + id: title.titleID, + mediatype, + size: title.size, + version: title.version, + _am: PhantomData, }) .collect()) } diff --git a/ctru-rs/src/services/apt.rs b/ctru-rs/src/services/apt.rs index e885adf..1fba0e5 100644 --- a/ctru-rs/src/services/apt.rs +++ b/ctru-rs/src/services/apt.rs @@ -13,9 +13,9 @@ pub struct Apt(()); impl Apt { /// Initialize a new service handle. - /// + /// /// # Example - /// + /// /// ```no_run /// # use std::error::Error; /// # fn main() -> Result<(), Box> { @@ -43,20 +43,20 @@ impl Apt { /// 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(()) diff --git a/ctru-rs/src/services/gfx.rs b/ctru-rs/src/services/gfx.rs index e6465e4..1e9a048 100644 --- a/ctru-rs/src/services/gfx.rs +++ b/ctru-rs/src/services/gfx.rs @@ -220,7 +220,7 @@ static GFX_ACTIVE: Mutex = Mutex::new(0); impl Gfx { /// Initialize a new default service handle. - /// + /// /// It's the same as calling: /// /// ```no_run diff --git a/ctru-rs/src/services/ps.rs b/ctru-rs/src/services/ps.rs index fc108fd..fc20a78 100644 --- a/ctru-rs/src/services/ps.rs +++ b/ctru-rs/src/services/ps.rs @@ -1,14 +1,15 @@ -//! 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). +//! Process Services. +//! +//! This service handles miscellaneous utility tasks used by the various processes. +//! However, it is particularly important because it is used to generate cryptographically secure random data, which +//! is required for commonly used functionality such as hashing (e.g. [`HashMap`](std::collections::HashMap) will not work without it). +//! //! See also use crate::error::ResultCode; use crate::Result; -/// Kind of AES algorithm to use. +/// Type of AES algorithm to use. #[doc(alias = "PS_AESAlgorithm")] #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u32)] @@ -59,6 +60,20 @@ pub struct Ps(()); impl Ps { /// Initialize a new service handle. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::ps::Ps; + /// + /// let ps = Ps::new()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "psInit")] pub fn new() -> Result { unsafe { @@ -68,6 +83,21 @@ impl Ps { } /// Returns the console's local friend code seed. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::ps::Ps; + /// let ps = Ps::new()?; + /// + /// let friend_code_seed = ps.local_friend_code_seed()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "PS_GetLocalFriendCodeSeed")] pub fn local_friend_code_seed(&self) -> crate::Result { let mut seed: u64 = 0; @@ -77,6 +107,21 @@ impl Ps { } /// Returns the console's devide ID. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::ps::Ps; + /// let ps = Ps::new()?; + /// + /// let device_id = ps.device_id()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "PS_GetDeviceId")] pub fn device_id(&self) -> crate::Result { let mut id: u32 = 0; @@ -86,6 +131,24 @@ impl Ps { } /// Generates cryptografically secure random bytes and writes them into the `out` buffer. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::ps::Ps; + /// let ps = Ps::new()?; + /// + /// let mut buffer = vec![0; 128]; + /// + /// // The buffer is now randomized! + /// ps.generate_random_bytes(&mut buffer)?; + /// # + /// # Ok(()) + /// # } + /// ``` #[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 c1c2d9e..ad5429f 100644 --- a/ctru-rs/src/services/romfs.rs +++ b/ctru-rs/src/services/romfs.rs @@ -1,9 +1,14 @@ //! Read-Only Memory FileSystem service. //! +//! This service lets the application access a virtual mounted device created using a folder included within the application bundle. +//! 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:/`. +//! +//! # Usage +//! //! This module only gets compiled if the configured RomFS directory is found and the `romfs` //! feature is enabled. //! -//! Configure the path in Cargo.toml (the default path is "romfs"). Paths are relative to the +//! Configure the path in your project's `Cargo.toml` manifest (the default path is "romfs"). Paths are relative to the //! `CARGO_MANIFEST_DIR` environment variable, which is the directory containing the manifest of //! your package. //! @@ -11,6 +16,8 @@ //! [package.metadata.cargo-3ds] //! romfs_dir = "romfs" //! ``` +//! +//! Alternatively, you can include the RomFS archive manually when building with `3dsxtool`. use crate::error::ResultCode; use std::ffi::CStr; @@ -19,11 +26,6 @@ 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-rs` 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, } @@ -31,7 +33,24 @@ pub struct RomFS { static ROMFS_ACTIVE: Mutex = Mutex::new(0); impl RomFS { - /// Mount the specified RomFS folder as a virtual drive. + /// Mount the bundled RomFS archive as a virtual drive. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::romfs::RomFS; + /// + /// let romfs = RomFS::new()?; + /// + /// // Remember to include the RomFS archive and to use your actual files! + /// let contents = std::fs::read_to_string("romfs:/test-file.txt"); + /// # + /// # Ok(()) + /// # } + /// ``` #[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 aa450be..f9cc258 100644 --- a/ctru-rs/src/services/soc.rs +++ b/ctru-rs/src/services/soc.rs @@ -1,4 +1,7 @@ //! Network Socket service. +//! +//! By using this service the program enables the use of network sockets and utilities such as those found in `std::net`, which are completely inaccessible by default. +//! As such, remember to hold a handle to this service handle while using any network functionality, or else the `std::net` methods will return generic OS errors. use libc::memalign; use std::net::Ipv4Addr; @@ -8,10 +11,7 @@ use crate::error::ResultCode; use crate::services::ServiceReference; use crate::Error; -/// Network socket service -/// -/// Initializing this service will enable the use of network sockets and utilities -/// such as those found in `std::net`. The service will close once this struct gets dropped. +/// Handle to the Network Socket service. pub struct Soc { _service_handler: ServiceReference, sock_3dslink: libc::c_int, @@ -20,22 +20,51 @@ pub struct Soc { static SOC_ACTIVE: Mutex = Mutex::new(0); impl Soc { - /// Initialize a new service handle using a socket 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 being used. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::soc::Soc; + /// + /// let soc = Soc::new()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "socInit")] pub fn new() -> crate::Result { Self::init_with_buffer_size(0x100000) } - /// Initialize the Soc service with a custom buffer size in bytes. The size should be - /// 0x100000 bytes or greater. + /// Initialize a new service handle using a custom socket buffer size. + /// + /// The size should be `0x100000` bytes or greater. /// /// # 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 being used. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::soc::Soc; + /// + /// let soc = Soc::init_with_buffer_size(0x100000)?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "socInit")] pub fn init_with_buffer_size(num_bytes: usize) -> crate::Result { let _service_handler = ServiceReference::new( @@ -62,20 +91,55 @@ impl Soc { }) } - /// IP Address of the Nintendo 3DS system. + /// Returns the local IP Address of the Nintendo 3DS system. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::soc::Soc; + /// let soc = Soc::new()?; + /// + /// let address = soc.host_address(); + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "gethostid")] pub fn host_address(&self) -> Ipv4Addr { let raw_id = unsafe { libc::gethostid() }; Ipv4Addr::from(raw_id.to_ne_bytes()) } - /// Redirect output streams (i.e. [`println`] and [`eprintln`]) to the `3dslink` server. - /// Requires `3dslink` >= 0.6.1 and `new-hbmenu` >= 2.3.0. + /// Redirect output streams (i.e. `println` and `eprintln`) to the `3dslink` server. + /// + /// Requires `3dslink` >= 0.6.1 and `new-hbmenu` >= 2.3.0 and the use of the `--server` flag. + /// The `--server` flag is also availble to use via `cargo-3ds` if the requirements are met. /// /// # Errors /// - /// Returns an error if a connection cannot be established to the server, or - /// output was already previously redirected. + /// Returns an error if a connection cannot be established to the server, + /// or if the output was already being redirected. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::soc::Soc; + /// let mut soc = Soc::new()?; + /// + /// // Redirect to the `3dslink` server that sent this program. + /// let address = soc.redirect_to_3dslink(true, true)?; + /// + /// println!("I'm visible from a PC!"); + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "link3dsConnectToHost")] pub fn redirect_to_3dslink(&mut self, stdout: bool, stderr: bool) -> crate::Result<()> { if self.sock_3dslink >= 0 { diff --git a/ctru-rs/src/services/sslc.rs b/ctru-rs/src/services/sslc.rs index b13fac0..af8b65d 100644 --- a/ctru-rs/src/services/sslc.rs +++ b/ctru-rs/src/services/sslc.rs @@ -9,6 +9,20 @@ pub struct SslC(()); impl SslC { /// Initialize a new service handle. + /// + /// # Example + /// + /// ```no_run + /// # use std::error::Error; + /// # fn main() -> Result<(), Box> { + /// # + /// use ctru::services::sslc::SslC; + /// + /// let sslc = SslC::new()?; + /// # + /// # Ok(()) + /// # } + /// ``` #[doc(alias = "sslcInit")] pub fn new() -> crate::Result { unsafe {