diff --git a/ctru-rs/Cargo.toml b/ctru-rs/Cargo.toml index bf2ec15..8049fea 100644 --- a/ctru-rs/Cargo.toml +++ b/ctru-rs/Cargo.toml @@ -5,6 +5,7 @@ license = "Zlib" name = "ctru-rs" version = "0.7.1" edition = "2021" +repository = "https://github.com/rust3ds/ctru-rs" rust-version = "1.64" [lib] diff --git a/ctru-rs/src/error.rs b/ctru-rs/src/error.rs index 004b461..9e1f3c5 100644 --- a/ctru-rs/src/error.rs +++ b/ctru-rs/src/error.rs @@ -1,3 +1,6 @@ +//! Error handling interface. +//! +//! This module holds the generic error and result types to interface with [`ctru_sys`] and the safe wrapper. use std::borrow::Cow; use std::error; use std::ffi::CStr; @@ -6,8 +9,27 @@ use std::ops::{ControlFlow, FromResidual, Try}; use ctru_sys::result::{R_DESCRIPTION, R_LEVEL, R_MODULE, R_SUMMARY}; +/// Custom type alias for generic `ctru` operations. +/// +/// This type is compatible with `ctru-sys` result codes. pub type Result = ::std::result::Result; +/// Validity checker of raw [`ctru_sys::Result`] codes. +/// +/// This struct supports the "try" syntax (`?`) to convert to an [`Error::Os`]. +/// +/// # Example +/// +/// ```no_run +/// pub fn hid_init() -> crate::Result<()> { +/// // We run an unsafe function which returns a `ctru_sys::Result`. +/// let result: ctru_sys::Result = unsafe { ctru_sys::hidInit() }; +/// +/// // The result code is parsed and any possible error gets returned by the function. +/// ResultCode(result)?; +/// Ok(()) +/// } +/// ``` #[derive(Debug, Copy, Clone, PartialEq, PartialOrd, Eq, Ord)] #[repr(transparent)] pub struct ResultCode(pub ctru_sys::Result); @@ -48,13 +70,20 @@ impl FromResidual for Result { } } -/// The error type returned by all libctru functions. +/// The generic error enum returned by `ctru` functions. +/// +/// This error enum supports parsing and displaying [`ctru_sys::Result`] codes. #[non_exhaustive] pub enum Error { + /// Raw [`ctru_sys::Result`] codes. Os(ctru_sys::Result), + /// Generic `libc` error codes. Libc(String), + /// Requested service is already active and cannot be activated again. ServiceAlreadyActive, + /// `stdout` is already being redirected. OutputAlreadyRedirected, + /// The buffer provided by the user to store some data is shorter than required. BufferTooShort { /// Length of the buffer provided by the user. provided: usize, @@ -64,8 +93,9 @@ pub enum Error { } impl Error { - /// Create an [`Error`] out of the last set value in `errno`. This can be used - /// to get a human-readable error string from calls to `libc` functions. + /// Create an [`Error`] out of the last set value in `errno`. + /// + /// This can be used to get a human-readable error string from calls to `libc` functions. pub(crate) fn from_errno() -> Self { let error_str = unsafe { let errno = ctru_sys::errno(); diff --git a/ctru-rs/src/lib.rs b/ctru-rs/src/lib.rs index 92645dd..713705e 100644 --- a/ctru-rs/src/lib.rs +++ b/ctru-rs/src/lib.rs @@ -17,7 +17,6 @@ //! # Examples //! //! You can check out the examples provided with this crate which dive into most of the implemented functionality. -//! #![crate_type = "rlib"] #![crate_name = "ctru"] @@ -39,6 +38,9 @@ extern crate pthread_3ds; extern crate shim_3ds; +/// Expanded stack size used to spawn the main thread by `libctru`. +/// +/// This value was chosen to support crate dependencies which expected more stack than provided, without compromising performance. #[no_mangle] #[cfg(feature = "big-stack")] static __stacksize__: usize = 2 * 1024 * 1024; // 2MB @@ -53,19 +55,24 @@ macro_rules! from_impl { }; } -/// Activate the default panic handler. +/// Activate the custom `ctru` panic handler. /// /// With this implementation, the main thread will stop and try to print debug info to an available [`Console`](console::Console). /// In case it fails to find an active [`Console`](console::Console) the program will just exit. /// /// # Notes /// -/// When ´test´ is enabled, this function won't do anything, as it should be overridden by the ´test´ environment. +/// When ´test´ is enabled, this function will not do anything, as it should be overridden by the ´test´ environment. pub fn use_panic_handler() { #[cfg(not(test))] panic_hook_setup(); } +/// Internal protocol to activate the custom panic handler hook. +/// +/// # Notes +/// +/// When `test` is enabled, this function will be ignored. #[cfg(not(test))] fn panic_hook_setup() { use crate::services::hid::{Hid, KeyPad};