From 8dc32b1e509b04ea7a052960bf7b49dce0927e12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hrvoje=20Nik=C5=A1i=C4=87?= Date: Thu, 25 Jan 2024 01:30:59 +0100 Subject: [PATCH] Explicitly document that pod_read_unaligned and try_pod_read_unaligned don't panic on unallowed reads (#220) * Explicitly document that pod_read_unaligned and try_pod_read_unaligned don't panic on unallowed reads Their names make that reasonably clear already, but it doesn't hurt to be explicit. Also, when choosing between `*from_bytes(x)` and `pod_read_unaligned(x)`, it's good to have a clearly documented criterion. * Cosmetic doc changes Add a couple of missing links, add a missing "like" (consistent with other similar sentences). * Remove redundant link The redundant link emits a warning in `cargo doc`. --- src/checked.rs | 2 +- src/lib.rs | 18 +++++++++++++----- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/src/checked.rs b/src/checked.rs index 722c31d..ae45823 100644 --- a/src/checked.rs +++ b/src/checked.rs @@ -450,7 +450,7 @@ pub fn pod_read_unaligned(bytes: &[u8]) -> T { /// /// ## Panics /// -/// * This is like [`try_cast`](try_cast), but will panic on a size mismatch. +/// * This is like [`try_cast`], but will panic on a size mismatch. #[inline] pub fn cast(a: A) -> B { match try_cast(a) { diff --git a/src/lib.rs b/src/lib.rs index 203a0fb..fb99c34 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -234,7 +234,7 @@ pub fn bytes_of_mut(t: &mut T) -> &mut [u8] { /// /// ## Panics /// -/// This is [`try_from_bytes`] but will panic on error. +/// This is like [`try_from_bytes`] but will panic on error. #[inline] pub fn from_bytes(s: &[u8]) -> &T { unsafe { internal::from_bytes(s) } @@ -244,7 +244,7 @@ pub fn from_bytes(s: &[u8]) -> &T { /// /// ## Panics /// -/// This is [`try_from_bytes_mut`] but will panic on error. +/// This is like [`try_from_bytes_mut`] but will panic on error. #[inline] pub fn from_bytes_mut(s: &mut [u8]) -> &mut T { unsafe { internal::from_bytes_mut(s) } @@ -252,6 +252,9 @@ pub fn from_bytes_mut(s: &mut [u8]) -> &mut T { /// Reads from the bytes as if they were a `T`. /// +/// Unlike [`from_bytes`], the slice doesn't need to respect alignment of `T`, only sizes +/// must match. +/// /// ## Failure /// * If the `bytes` length is not equal to `size_of::()`. #[inline] @@ -263,6 +266,9 @@ pub fn try_pod_read_unaligned( /// Reads the slice into a `T` value. /// +/// Unlike [`from_bytes`], the slice doesn't need to respect alignment of `T`, only sizes +/// must match. +/// /// ## Panics /// * This is like `try_pod_read_unaligned` but will panic on failure. #[inline] @@ -298,7 +304,7 @@ pub fn try_from_bytes_mut( /// /// ## Panics /// -/// * This is like [`try_cast`](try_cast), but will panic on a size mismatch. +/// * This is like [`try_cast`], but will panic on a size mismatch. #[inline] pub fn cast(a: A) -> B { unsafe { internal::cast(a) } @@ -351,7 +357,8 @@ pub fn cast_slice_mut< unsafe { internal::cast_slice_mut(a) } } -/// As `align_to`, but safe because of the [`Pod`] bound. +/// As [`align_to`](https://doc.rust-lang.org/std/primitive.slice.html#method.align_to), +/// but safe because of the [`Pod`] bound. #[inline] pub fn pod_align_to( vals: &[T], @@ -359,7 +366,8 @@ pub fn pod_align_to( unsafe { vals.align_to::() } } -/// As `align_to_mut`, but safe because of the [`Pod`] bound. +/// As [`align_to_mut`](https://doc.rust-lang.org/std/primitive.slice.html#method.align_to_mut), +/// but safe because of the [`Pod`] bound. #[inline] pub fn pod_align_to_mut< T: NoUninit + AnyBitPattern,