From ed5a72dce97512a2fdb3623c1beccec16d90ea44 Mon Sep 17 00:00:00 2001
From: bluurryy <164359728+bluurryy@users.noreply.github.com>
Date: Thu, 22 Aug 2024 15:05:06 +0200
Subject: [PATCH] doc: improve `Mut*` collections docs

---
 src/bump_scope.rs       | 4 ++++
 src/lib.rs              | 2 +-
 src/mut_bump_string.rs  | 8 ++++++++
 src/mut_bump_vec.rs     | 8 ++++++--
 src/mut_bump_vec_rev.rs | 6 ++++--
 5 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/src/bump_scope.rs b/src/bump_scope.rs
index 5050016..e6c102b 100644
--- a/src/bump_scope.rs
+++ b/src/bump_scope.rs
@@ -144,6 +144,8 @@ where
                 let dst = nonnull::sub(dst_end, len);
 
                 // We only copy if we can do so nonoverlappingly.
+                // TODO: How about we don't? This is surprising, let's not.
+                //       This also makes the docs wrong saying that "unused capacity does not take up space".
                 if dst >= end {
                     nonnull::copy_nonoverlapping(start, dst, len);
                     start = dst;
@@ -165,6 +167,8 @@ where
                 let dst_end = nonnull::add(dst, len);
 
                 // We only copy if we can do so nonoverlappingly.
+                // TODO: How about we don't? This is surprising, let's not.
+                //       This also makes the docs wrong saying that "unused capacity does not take up space".
                 if dst_end <= start {
                     nonnull::copy_nonoverlapping(start, dst, len);
                     start = dst;
diff --git a/src/lib.rs b/src/lib.rs
index 12d454a..c509bd6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -213,7 +213,7 @@
 //! * **`alloc`** —  Adds `Global` as the default allocator, `BumpBox::into_box` and some interactions with `alloc` collections.
 //! * **`serde`** —  Adds `Serialize` implementations for `BumpBox`, strings and vectors, and `DeserializeSeed` for strings and vectors.
 //! * **`zerocopy`** —  Adds `alloc_zeroed(_slice)`, `init_zeroed`, `resize_zeroed` and `extend_zeroed`.
-//! 
+//!
 //!  ### Nightly features
 //! * **`nightly-allocator-api`** —  Enables `allocator-api2`'s `nightly` feature which makes it reexport the nightly allocator api instead of its own implementation.
 //!   With this you can bump allocate collections from the standard library.
diff --git a/src/mut_bump_string.rs b/src/mut_bump_string.rs
index 25ef811..3222d2a 100644
--- a/src/mut_bump_string.rs
+++ b/src/mut_bump_string.rs
@@ -60,6 +60,8 @@ macro_rules! mut_bump_format {
 macro_rules! mut_bump_string_declaration {
     ($($allocator_parameter:tt)*) => {
         /// A type like [`BumpString`](crate::BumpString), optimized for a `&mut Bump(Scope)`.
+        /// It has the advantage that it can assume the entire remaining chunk space as its capacity.
+        /// It also only needs to update the bump pointer when calling <code>[into_](Self::into_str)([boxed_](Self::into_boxed_str))[str](Self::into_str)</code>.
         ///
         /// When you are done building the string, you can turn it into a `&str` with [`into_str`].
         ///
@@ -579,6 +581,9 @@ where
     }
 
     /// Converts a `MutBumpString` into a `BumpBox<str>`.
+    ///
+    /// Unused capacity does not take up space.<br/>
+    /// When [bumping downwards](crate#bumping-upwards-or-downwards) this needs to shift all elements to the other end of the chunk.
     #[must_use]
     #[inline(always)]
     pub fn into_boxed_str(self) -> BumpBox<'a, str> {
@@ -586,6 +591,9 @@ where
     }
 
     /// Converts this `BumpBox<str>` into `&str` that is live for the entire bump scope.
+    ///
+    /// Unused capacity does not take up space.<br/>
+    /// When [bumping downwards](crate#bumping-upwards-or-downwards) this needs to shift all elements to the other end of the chunk.
     #[must_use]
     #[inline(always)]
     pub fn into_str(self) -> &'a mut str {
diff --git a/src/mut_bump_vec.rs b/src/mut_bump_vec.rs
index bb71bc0..a94b5ff 100644
--- a/src/mut_bump_vec.rs
+++ b/src/mut_bump_vec.rs
@@ -99,6 +99,8 @@ macro_rules! mut_bump_vec {
 macro_rules! mut_bump_vec_declaration {
     ($($allocator_parameter:tt)*) => {
         /// A type like [`BumpVec`](crate::BumpVec), optimized for a `&mut Bump(Scope)`.
+        /// It has the advantage that it can assume the entire remaining chunk space as its capacity.
+        /// It also only needs to update the bump pointer when calling <code>[into_](Self::into_slice)([boxed_](Self::into_boxed_slice))[slice](Self::into_slice)</code>.
         ///
         /// This type can be used to allocate a slice, when `alloc_*` methods are too limiting:
         /// ```
@@ -1073,7 +1075,8 @@ where
 
     /// Turns this `MutBumpVec<T>` into a `BumpBox<[T]>`.
     ///
-    /// Unused capacity does not take up space.
+    /// Unused capacity does not take up space.<br/>
+    /// When [bumping downwards](crate#bumping-upwards-or-downwards) this needs to shift all elements to the other end of the chunk.
     #[must_use]
     #[inline(always)]
     pub fn into_boxed_slice(self) -> BumpBox<'a, [T]> {
@@ -1082,7 +1085,8 @@ where
 
     /// Turns this `MutBumpVec<T>` into a `&[T]` that is live for the entire bump scope.
     ///
-    /// Unused capacity does not take up space.
+    /// Unused capacity does not take up space.<br/>
+    /// When [bumping downwards](crate#bumping-upwards-or-downwards) this needs to shift all elements to the other end of the chunk.
     ///
     /// This is only available for [`NoDrop`] types so you don't omit dropping a value for which it matters.
     ///
diff --git a/src/mut_bump_vec_rev.rs b/src/mut_bump_vec_rev.rs
index 4cefd1c..91f95b4 100644
--- a/src/mut_bump_vec_rev.rs
+++ b/src/mut_bump_vec_rev.rs
@@ -1137,7 +1137,8 @@ where
 
     /// Turns this `MutBumpVecRev<T>` into a `BumpBox<[T]>`.
     ///
-    /// Unused capacity does not take up space.
+    /// Unused capacity does not take up space.<br/>
+    /// When [bumping upwards](crate#bumping-upwards-or-downwards) this needs to shift all elements to the other end of the chunk.
     #[must_use]
     #[inline(always)]
     pub fn into_boxed_slice(self) -> BumpBox<'a, [T]> {
@@ -1146,7 +1147,8 @@ where
 
     /// Turns this `MutBumpVecRev<T>` into a `&[T]` that is live for the entire bump scope.
     ///
-    /// Unused capacity does not take up space.
+    /// Unused capacity does not take up space.<br/>
+    /// When [bumping upwards](crate#bumping-upwards-or-downwards) this needs to shift all elements to the other end of the chunk.
     ///
     /// This is only available for [`NoDrop`] types so you don't omit dropping a value for which it matters.
     ///