From d4976311666f24c9ae8b8b37021476a7c56fd9ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Antinori?= Date: Tue, 30 Jun 2026 15:43:12 -0300 Subject: [PATCH] docs: document preferences for Zeroable::zeroed vs pin_init::zeroed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Modify the comments in `pin_init::zeroed` and `Zeroable::zeroed` functions to clarify to the user when one is preferred over the other. This also adapts the example code in `Zeroable::zeroed` doc comments to use that function. Link: https://lore.kernel.org/rust-for-linux/CANiq72m80vip+hz5RngvgH4VxU30amzS-ePr6KVKwKvhf3=Ycg@mail.gmail.com/T/#t Suggested-by: Miguel Ojeda Signed-off-by: Nicolás Antinori --- src/lib.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index fd40c8f2..3f4a6bfb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1510,10 +1510,13 @@ pub unsafe trait Zeroable { /// Whenever a type implements [`Zeroable`], this function should be preferred over /// [`core::mem::zeroed()`] or using `MaybeUninit::zeroed().assume_init()`. /// + /// This function is preferred over [`pin_init::zeroed()`], unless initializing in a + /// `const` context or if the object is pinned. + /// /// # Examples /// /// ``` - /// use pin_init::{Zeroable, zeroed}; + /// use pin_init::Zeroable; /// /// #[derive(Zeroable)] /// struct Point { @@ -1521,7 +1524,7 @@ pub unsafe trait Zeroable { /// y: u32, /// } /// - /// let point: Point = zeroed(); + /// let point: Point = Zeroable::zeroed(); /// assert_eq!(point.x, 0); /// assert_eq!(point.y, 0); /// ``` @@ -1553,6 +1556,9 @@ pub fn init_zeroed() -> impl Init { /// Whenever a type implements [`Zeroable`], this function should be preferred over /// [`core::mem::zeroed()`] or using `MaybeUninit::zeroed().assume_init()`. /// +/// This function should be used in `const` contexts (as it is a `const fn`) or when +/// dealing with pinned objects, where it is preferred over [`Zeroable::zeroed()`]. +/// /// # Examples /// /// ```