doc: improve vector docs

src/bump_vec.rs

@@ -102,28 +102,13 @@ macro_rules! bump_vec {
 
 macro_rules! bump_vec_declaration {
     ($($allocator_parameter:tt)*) => {
-        /// A bump allocated `Vec`.
+        /// A bump allocated [`Vec`](alloc::vec::Vec).
         ///
-        /// This type can be used to allocate a slice, when `alloc_*` methods are too limiting:
-        /// ```
-        /// use bump_scope::{ Bump, BumpVec };
-        /// let bump: Bump = Bump::new();
-        /// let mut vec = BumpVec::new_in(&bump);
+        /// The main difference to `Vec` is that it can be turned into a slice that is live for this bump scope (`'a`).
+        /// Such a slice can be live while entering new scopes.
         ///
-        /// vec.push(1);
-        /// vec.push(2);
-        /// vec.push(3);
+        /// This would not be possible with `Vec`:
         ///
-        /// let slice: &[i32] = vec.into_slice();
-        ///
-        /// assert_eq!(slice, [1, 2, 3]);
-        /// ```
-        ///
-        /// ## Why not just use a [`Vec`]?
-        ///
-        /// You can use a `Vec` (from the standard library or from allocator-api2) in mostly the same way.
-        /// The main difference is that a `BumpVec` can be turned into a slice that is live for `'a` of `BumpScope<'a>` instead of just `'b` of `&'b BumpScope`.
-        /// This enables such a slice to be live while entering new scopes. This would not be possible with `Vec`:
         /// ```
         /// # use bump_scope::{ Bump, BumpVec };
         /// # let mut bump: Bump = Bump::new();
@@ -145,6 +130,23 @@ macro_rules! bump_vec_declaration {
         ///
         /// assert_eq!(slice, [1, 2, 3]);
         /// ```
+        ///
+        /// # Examples
+        ///
+        /// This type can be used to allocate a slice, when `alloc_*` methods are too limiting:
+        /// ```
+        /// use bump_scope::{ Bump, BumpVec };
+        /// let bump: Bump = Bump::new();
+        /// let mut vec = BumpVec::new_in(&bump);
+        ///
+        /// vec.push(1);
+        /// vec.push(2);
+        /// vec.push(3);
+        ///
+        /// let slice: &[i32] = vec.into_slice();
+        ///
+        /// assert_eq!(slice, [1, 2, 3]);
+        /// ```
         pub struct BumpVec<
             'b,
             'a: 'b,

src/mut_bump_vec.rs

@@ -100,6 +100,8 @@ macro_rules! mut_bump_vec_declaration {
         /// 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>.
         ///
+        /// # Examples
+        ///
         /// This type can be used to allocate a slice, when `alloc_*` methods are too limiting:
         /// ```
         /// use bump_scope::{ Bump, MutBumpVec };

src/mut_bump_vec_rev.rs

@@ -96,7 +96,7 @@ macro_rules! mut_bump_vec_rev {
 
 macro_rules! mut_bump_vec_rev_declaration {
     ($($allocator_parameter:tt)*) => {
-        /// This is like a [`MutBumpVec`](crate::MutBumpVec), but new elements are pushed to the front.
+        /// A type like [`MutBumpVec`](crate::MutBumpVec), but new elements are pushed to the front.
         ///
         /// The point of this vector is to have a more performant <code>[into](Self::into_slice)([_boxed](Self::into_boxed_slice))[_slice](Self::into_slice)`</code> for a downwards bumping allocator.
         ///
@@ -128,6 +128,14 @@ macro_rules! mut_bump_vec_rev_declaration {
         ///
         /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
         /// ```
+        //
+        // MutBumpVecRev never actually moves a bump pointer.
+        // It may force allocation of a new chunk, but it does not move the pointer within.
+        // So we don't need to move the bump pointer when dropping.
+        //
+        // If we want to reset the bump pointer to a previous chunk, we use a bump scope.
+        // We could do it here, by resetting to the last non-empty chunk but that would require a loop.
+        // Chunk allocations are supposed to be very rare, so this wouldn't be worth it.
         pub struct MutBumpVecRev<
             'b,
             'a: 'b,