From 7a5154ba8b54970b7bb07c4902bc8a7981f4e57c Mon Sep 17 00:00:00 2001
From: Paolo Barbolini <paolo@paolo565.org>
Date: Fri, 21 Jun 2024 14:07:25 +0200
Subject: [PATCH] Clarify how `BytesMut::zeroed` works and advantages to manual
 impl (#714)

---
 src/bytes_mut.rs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/bytes_mut.rs b/src/bytes_mut.rs
index 537f01ad3..a01b29634 100644
--- a/src/bytes_mut.rs
+++ b/src/bytes_mut.rs
@@ -264,7 +264,14 @@ impl BytesMut {
         }
     }
 
-    /// Creates a new `BytesMut`, which is initialized with zero.
+    /// Creates a new `BytesMut` containing `len` zeros.
+    ///
+    /// The resulting object has a length of `len` and a capacity greater
+    /// than or equal to `len`. The entire length of the object will be filled
+    /// with zeros.
+    ///
+    /// On some platforms or allocators this function may be faster than
+    /// a manual implementation.
     ///
     /// # Examples
     ///
@@ -273,6 +280,7 @@ impl BytesMut {
     ///
     /// let zeros = BytesMut::zeroed(42);
     ///
+    /// assert!(zeros.capacity() >= 42);
     /// assert_eq!(zeros.len(), 42);
     /// zeros.into_iter().for_each(|x| assert_eq!(x, 0));
     /// ```