From c9e3a79c9cbc10867105a94037975c9013023d65 Mon Sep 17 00:00:00 2001 From: ROMemories Date: Mon, 15 Apr 2024 17:36:46 +0200 Subject: [PATCH] docs(random): fix a few typos and minor docs issues The second parameter of `*fill*()` functions has to be named `dest` because the documentation of these is provided on the trait and names that parameter that. --- src/riot-rs-random/src/lib.rs | 36 +++++++++++++++++------------------ src/riot-rs/Cargo.toml | 4 ++-- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/riot-rs-random/src/lib.rs b/src/riot-rs-random/src/lib.rs index 5f8e56a43..22a044e1e 100644 --- a/src/riot-rs-random/src/lib.rs +++ b/src/riot-rs-random/src/lib.rs @@ -2,7 +2,7 @@ //! //! The module provides functions for use by applications, [`fast_rng()`] and [`crypto_rng()`], //! which produce owned types that provide the [`rand_core::RngCore`] and -//! [`rand_core::CryptoRng`'] traits, respectively. +//! [`rand_core::CryptoRng`] traits, respectively. //! //! The crate abstracts over multiple aspects of RNGs: //! * Where do we take a valid seed for the RNG from? @@ -12,16 +12,16 @@ //! No matter the choices taken (eventually through the application's setup), all is hidden behind //! the [`FastRng`] and [`CryptoRng`] types. //! -//! Before accessing the RNG, it needs to be initialized through the [`construct_rng()`'] function. +//! Before accessing the RNG, it needs to be initialized through the [`construct_rng()`] function. //! This is taken care of by the `riot-rs-embassy` initialization functions. Applications can //! ensure that this has happened by depending on the laze feature `random`. //! //! --- //! //! Currently, this provides very little choice, and little fanciness: It (more or less -//! arbitrarily) uses the [rand_chacha::ChaCha20Rng] generator as a shared global RNG, and -//! [rand_pcg::Pcg32] is decided yet for the fast one. Neither the algorithm nor the size of -//! FastRng or CryptoRng is guaranteed. +//! arbitrarily) uses the [`rand_chacha::ChaCha20Rng`] generator as a shared global RNG, and +//! [`rand_pcg::Pcg32`] is decided yet for the fast one. Neither the algorithm nor the size of +//! [`FastRng`] or [`CryptoRng`] is guaranteed. #![no_std] use rand_core::{RngCore, SeedableRng}; @@ -33,7 +33,7 @@ static RNG: embassy_sync::blocking_mutex::Mutex< core::cell::RefCell>, > = embassy_sync::blocking_mutex::Mutex::new(core::cell::RefCell::new(None)); -/// Type of the global RNG when needing the ability to produce cryptographially secure random +/// Type of the global RNG when needing the ability to produce cryptographically secure random /// numbers. /// /// If calls to [`rng()`] are rare, it may even make sense to move the HWRNG in here to get a @@ -47,11 +47,11 @@ pub(crate) type SelectedRng = rand_pcg::Pcg32; /// Locks the global RNG for a single operation. /// -/// ## Panics +/// # Panics /// /// … if initialization did not happen. /// -/// ## Deadlocks +/// # Deadlocks /// /// … if the action attempts to lock RNG. fn with_global(action: impl FnOnce(&mut SelectedRng) -> R) -> R { @@ -84,11 +84,11 @@ impl RngCore for FastRng { fn next_u64(&mut self) -> u64 { self.inner.next_u64() } - fn fill_bytes(&mut self, buf: &mut [u8]) { - self.inner.fill_bytes(buf) + fn fill_bytes(&mut self, dest: &mut [u8]) { + self.inner.fill_bytes(dest) } - fn try_fill_bytes(&mut self, buf: &mut [u8]) -> Result<(), rand_core::Error> { - self.inner.try_fill_bytes(buf) + fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand_core::Error> { + self.inner.try_fill_bytes(dest) } } @@ -114,11 +114,11 @@ mod csprng { fn next_u64(&mut self) -> u64 { with_global(|i| i.next_u64()) } - fn fill_bytes(&mut self, buf: &mut [u8]) { - with_global(|i| i.fill_bytes(buf)) + fn fill_bytes(&mut self, dest: &mut [u8]) { + with_global(|i| i.fill_bytes(dest)) } - fn try_fill_bytes(&mut self, buf: &mut [u8]) -> Result<(), rand_core::Error> { - with_global(|i| i.try_fill_bytes(buf)) + fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand_core::Error> { + with_global(|i| i.try_fill_bytes(dest)) } } @@ -140,7 +140,7 @@ pub fn construct_rng(hwrng: impl RngCore) { }); } -/// Obtains a suitably initialized fast random number generator. +/// Returns a suitably initialized fast random number generator. #[inline] pub fn fast_rng() -> FastRng { FastRng { @@ -149,7 +149,7 @@ pub fn fast_rng() -> FastRng { } } -/// Obtains a suitably initialized cryptographically secure random number generator. +/// Returns a suitably initialized cryptographically secure random number generator. #[inline] #[cfg(feature = "csprng")] pub fn crypto_rng() -> CryptoRng { diff --git a/src/riot-rs/Cargo.toml b/src/riot-rs/Cargo.toml index 3f5884f7b..cc0da4acd 100644 --- a/src/riot-rs/Cargo.toml +++ b/src/riot-rs/Cargo.toml @@ -45,9 +45,9 @@ threading = [ ## Enables support for timeouts in the internal executor---required to use ## `embassy_time::Timer`. time = ["riot-rs-embassy/time"] -## Enables the `random` module. +## Enables the [`random`] module. random = ["riot-rs-random"] -## Enables a cryptographically seucre random number generator in the `random` module. +## Enables a cryptographically secure random number generator in the [`random`] module. csprng = ["riot-rs-random/csprng"] ## Enables seeding the random number generator from hardware. hwrng = ["riot-rs-embassy/hwrng"]