docs: document preferences for Zeroable::zeroed vs pin_init::zeroed

src/lib.rs

@@ -1510,18 +1510,21 @@ pub unsafe trait Zeroable {
     /// Whenever a type implements [`Zeroable`], this function should be preferred over
     /// [`core::mem::zeroed()`] or using `MaybeUninit<T>::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 {
     ///     x: u32,
     ///     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<T: Zeroable>() -> impl Init<T> {
 /// Whenever a type implements [`Zeroable`], this function should be preferred over
 /// [`core::mem::zeroed()`] or using `MaybeUninit<T>::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
 ///
 /// ```