From cd7a041180018810606b7fd38c5f605dff844a64 Mon Sep 17 00:00:00 2001
From: Andrea Ciliberti <meziu210@icloud.com>
Date: Fri, 7 Jul 2023 13:03:54 +0200
Subject: [PATCH] error module documentation

---
 ctru-rs/Cargo.toml   |  1 +
 ctru-rs/src/error.rs | 36 +++++++++++++++++++++++++++++++++---
 ctru-rs/src/lib.rs   | 13 ++++++++++---
 3 files changed, 44 insertions(+), 6 deletions(-)

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<T> = ::std::result::Result<T, Error>;
 
+/// 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<T> FromResidual<Error> for Result<T> {
     }
 }
 
-/// 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};