From ccb0676f3c0e5aa9d2c96e9afa1e8ce2c0b477ca Mon Sep 17 00:00:00 2001 From: Andrea Ciliberti Date: Wed, 26 Jul 2023 18:37:44 +0200 Subject: [PATCH] More generic doc changes --- ctru-rs/README.md | 1 - ctru-rs/src/error.rs | 11 ++++++----- ctru-rs/src/lib.rs | 4 ++-- ctru-rs/src/linear.rs | 18 ++++++++++-------- ctru-rs/src/services/am.rs | 2 +- ctru-rs/src/services/mod.rs | 4 ++-- 6 files changed, 21 insertions(+), 19 deletions(-) diff --git a/ctru-rs/README.md b/ctru-rs/README.md index 297c8cc..0cc8a79 100644 --- a/ctru-rs/README.md +++ b/ctru-rs/README.md @@ -1,7 +1,6 @@ # ctru-rs Safe and idiomatic Rust wrapper around [`libctru`](https://github.com/devkitPro/libctru). -This crate uses the bindings provided by [`ctru-sys`](../ctru-sys/). ## Getting Started diff --git a/ctru-rs/src/error.rs b/ctru-rs/src/error.rs index 895bed1..becfaef 100644 --- a/ctru-rs/src/error.rs +++ b/ctru-rs/src/error.rs @@ -1,6 +1,7 @@ //! Error handling interface. //! -//! This module holds the generic error and result types to interface with [`ctru_sys`] and the safe wrapper. +//! This module holds the generic error and result types to interface with `ctru_sys` and the [`ctru-rs`](crate) safe wrapper. + use std::borrow::Cow; use std::error; use std::ffi::CStr; @@ -9,12 +10,12 @@ 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. +/// Custom type alias for generic [`ctru-rs`](crate) operations. /// -/// This type is compatible with `ctru-sys` result codes. +/// This type is compatible with `ctru-sys::Result` codes. pub type Result = ::std::result::Result; -/// Validity checker of raw [`ctru_sys::Result`] codes. +/// Validity checker of raw `ctru_sys::Result` codes. /// /// This struct supports the "try" syntax (`?`) to convert to an [`Error::Os`]. /// @@ -72,7 +73,7 @@ impl FromResidual for Result { } } -/// The generic error enum returned by `ctru` functions. +/// The generic error enum returned by [`ctru-rs`](crate) functions. /// /// This error enum supports parsing and displaying [`ctru_sys::Result`] codes. #[non_exhaustive] diff --git a/ctru-rs/src/lib.rs b/ctru-rs/src/lib.rs index b2267f0..3686578 100644 --- a/ctru-rs/src/lib.rs +++ b/ctru-rs/src/lib.rs @@ -6,7 +6,7 @@ //! Thanks to it, developers can access the underlying system services and the console's hardware to develop userland applications //! (such as [HID devices](crate::services::hid), [network capabilities](crate::services::soc), [graphics](crate::services::gfx), [built-in cameras](crate::services::cam), etc.). //! -//! Among these features, `ctru-rs` also automatically includes functionality to properly integrate the Rust `std` with the console's operating system, +//! Among these features, [`ctru-rs`](crate) also automatically includes functionality to properly integrate the Rust `std` with the console's operating system, //! which the developer would otherwise need to implement manually. //! //! # Usage @@ -53,7 +53,7 @@ macro_rules! from_impl { }; } -/// Activate the custom `ctru-rs` panic handler. +/// Activate the custom [`ctru-rs`](crate) 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. diff --git a/ctru-rs/src/linear.rs b/ctru-rs/src/linear.rs index d0164c0..fd776be 100644 --- a/ctru-rs/src/linear.rs +++ b/ctru-rs/src/linear.rs @@ -1,11 +1,12 @@ -//! Linear memory allocator +//! LINEAR memory allocator. //! -//! Linear memory is a sector of the 3DS' RAM that binds virtual addresses exactly to the physical address. -//! As such, it is used for fast and safe memory sharing between services (and is especially needed for GPU and DSP). +//! LINEAR memory is a sector of the 3DS' RAM that binds virtual addresses exactly to the physical address. +//! As such, it is used for fast and safe memory sharing between hardware processors (such as the GPU and the DSP). //! -//! Resources:
-//!
-//! +//! # Additional Resources +//! +//! -
+//! - use std::alloc::{AllocError, Allocator, Layout}; use std::ptr::NonNull; @@ -15,13 +16,14 @@ use std::ptr::NonNull; // Sadly the linear memory allocator included in `libctru` doesn't implement `linearRealloc` at the time of these additions, // but the default fallback of the `std` will take care of that for us. -/// [`Allocator`](std::alloc::Allocator) struct for LINEAR memory +/// [`Allocator`](std::alloc::Allocator) struct for LINEAR memory. +/// /// To use this struct the main crate must activate the `allocator_api` unstable feature. #[derive(Copy, Clone, Default, Debug)] pub struct LinearAllocator; impl LinearAllocator { - /// Returns the amount of free space left in the LINEAR sector + /// Returns the amount of free space left in the LINEAR memory sector. #[doc(alias = "linearSpaceFree")] pub fn free_space() -> u32 { unsafe { ctru_sys::linearSpaceFree() } diff --git a/ctru-rs/src/services/am.rs b/ctru-rs/src/services/am.rs index e67282e..ee5a480 100644 --- a/ctru-rs/src/services/am.rs +++ b/ctru-rs/src/services/am.rs @@ -4,7 +4,7 @@ //! - Read the installed applications on the console and their information (depending on the install location). //! - Install compatible applications to the console. //! -//! TODO: `ctru-rs` doesn't support installing or uninstalling titles yet. +//! TODO: [`ctru-rs`](crate) doesn't support installing or uninstalling titles yet. use crate::error::ResultCode; use crate::services::fs::FsMediaType; diff --git a/ctru-rs/src/services/mod.rs b/ctru-rs/src/services/mod.rs index 9ff975e..8aadf87 100644 --- a/ctru-rs/src/services/mod.rs +++ b/ctru-rs/src/services/mod.rs @@ -3,13 +3,13 @@ //! Most of the 3DS console's functionalities (when writing user-land homebrew) are accessible via services, //! which need to be initialized before accessing any particular feature. //! -//! To ensure safety while using the underlying services, `ctru-rs` leverages Rust's lifetime model. +//! To ensure safety while using the underlying services, [`ctru-rs`](crate) leverages Rust's lifetime model. //! After initializing the handle for a specific service (e.g. [`Apt`](apt::Apt)) the service will be accessible as long as there is at least one handle "alive". //! As such, handles should be dropped *after* the use of a specific service. This is particularly important for services which are necessary for functionality //! "outside" their associated methods, such as [`RomFS`](romfs::RomFS), which creates an accessible virtual filesystem, or [`Soc`](soc::Soc), //! which enables all network communications via sockets. //! -//! In `ctru-rs` some services only allow a single handle to be created at a time, to ensure a safe and controlled environment. +//! In [`ctru-rs`](crate) some services only allow a single handle to be created at a time, to ensure a safe and controlled environment. pub mod am; pub mod apt;