From 3b6e2e29ee279a2536866a1a50c63893313c66cc Mon Sep 17 00:00:00 2001
From: bluurryy <164359728+bluurryy@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:30:18 +0200
Subject: [PATCH] doc: add more examples for fallible methods

---
 src/bump_string.rs       |  62 ++++++++++++--
 src/bump_vec.rs          | 162 +++++++++++++++++++++++++++++++------
 src/fixed_bump_string.rs |  65 +++++++++++++--
 src/fixed_bump_vec.rs    | 170 ++++++++++++++++++++++++++++++++++-----
 src/lib.rs               |   1 -
 src/mut_bump_string.rs   |  62 ++++++++++++--
 src/mut_bump_vec.rs      | 162 ++++++++++++++++++++++++++++++++-----
 src/mut_bump_vec_rev.rs  | 140 ++++++++++++++++++++++++++++----
 8 files changed, 720 insertions(+), 104 deletions(-)

diff --git a/src/bump_string.rs b/src/bump_string.rs
index 0104884..eb28b52 100644
--- a/src/bump_string.rs
+++ b/src/bump_string.rs
@@ -444,11 +444,11 @@ where
         do panics
         /// Panics if `idx` is larger than the `String`'s length, or if it does not
         /// lie on a [`char`] boundary.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, BumpString };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut s = BumpString::with_capacity_in(3, &bump);
         ///
         /// s.insert(0, 'f');
@@ -457,8 +457,21 @@ where
         ///
         /// assert_eq!("foo", s);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, BumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut s = BumpString::try_with_capacity_in(3, &bump)?;
+        ///
+        /// s.try_insert(0, 'f')?;
+        /// s.try_insert(1, 'o')?;
+        /// s.try_insert(2, 'o')?;
+        ///
+        /// assert_eq!("foo", s);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, idx: usize, ch: char) {
             assert!(self.is_char_boundary(idx));
@@ -477,19 +490,30 @@ where
         do panics
         /// Panics if `idx` is larger than the `BumpString`'s length, or if it does not
         /// lie on a [`char`] boundary.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, BumpString };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut s = BumpString::from_str_in("bar", &bump);
         ///
         /// s.insert_str(0, "foo");
         ///
         /// assert_eq!("foobar", s);
         /// ```
-        impl
         for fn insert_str
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, BumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut s = BumpString::try_from_str_in("bar", &bump)?;
+        ///
+        /// s.try_insert_str(0, "foo")?;
+        ///
+        /// assert_eq!("foobar", s);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert_str
         use fn generic_insert_str(&mut self, idx: usize, string: &str) {
             assert!(self.is_char_boundary(idx));
@@ -503,11 +527,11 @@ where
         do panics
         /// Panics if the starting point or end point do not lie on a [`char`]
         /// boundary, or if they're out of bounds.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, BumpString };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut string = BumpString::from_str_in("abcde", &bump);
         ///
         /// string.extend_from_within(2..);
@@ -519,8 +543,24 @@ where
         /// string.extend_from_within(4..8);
         /// assert_eq!(string, "abcdecdeabecde");
         /// ```
-        impl
         for fn extend_from_within
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, BumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut string = BumpString::try_from_str_in("abcde", &bump)?;
+        ///
+        /// string.try_extend_from_within(2..)?;
+        /// assert_eq!(string, "abcdecde");
+        ///
+        /// string.try_extend_from_within(..2)?;
+        /// assert_eq!(string, "abcdecdeab");
+        ///
+        /// string.try_extend_from_within(4..8)?;
+        /// assert_eq!(string, "abcdecdeabecde");
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within
         use fn generic_extend_from_within<{R}>(&mut self, src: R)
         where {
@@ -545,6 +585,16 @@ where
         /// assert_eq!(string, "What?\0\0\0");
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, BumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut string = BumpString::try_from_str_in("What?", &bump)?;
+        /// string.try_extend_zeroed(3)?;
+        /// assert_eq!(string, "What?\0\0\0");
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize) {
             self.generic_reserve(additional)?;
diff --git a/src/bump_vec.rs b/src/bump_vec.rs
index 0acff00..d102bd7 100644
--- a/src/bump_vec.rs
+++ b/src/bump_vec.rs
@@ -600,8 +600,7 @@ where
     error_behavior_generic_methods_allocation_failure! {
         /// Appends an element to the back of a collection.
         impl
-        /// # Examples
-        ///
+        do examples
         /// ```
         /// # use bump_scope::{ bump_vec, Bump };
         /// # let bump: Bump = Bump::new();
@@ -610,6 +609,16 @@ where
         /// assert_eq!(vec, [1, 2, 3]);
         /// ```
         for fn push
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ bump_vec, Bump };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 1, 2]?;
+        /// vec.try_push(3);
+        /// assert_eq!(vec, [1, 2, 3]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_push
         use fn generic_push(&mut self, value: T) {
             self.generic_push_with(|| value)
@@ -630,6 +639,7 @@ where
         /// Inserts an element at position `index` within the vector, shifting all elements after it to the right.
         do panics
         /// Panics if `index > len`.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ bump_vec, Bump, BumpVec };
@@ -640,8 +650,19 @@ where
         /// vec.insert(4, 5);
         /// assert_eq!(vec, [1, 4, 2, 3, 5]);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ bump_vec, Bump, BumpVec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_insert(1, 4)?;
+        /// assert_eq!(vec, [1, 4, 2, 3]);
+        /// vec.try_insert(4, 5)?;
+        /// assert_eq!(vec, [1, 4, 2, 3, 5]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, index: usize, element: T) {
             #[cold]
@@ -742,11 +763,11 @@ where
         do panics
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, bump_vec };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump_vec![in bump; 0, 1, 2, 3, 4];
         ///
         /// vec.extend_from_within_copy(2..);
@@ -758,8 +779,24 @@ where
         /// vec.extend_from_within_copy(4..8);
         /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_copy
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 0, 1, 2, 3, 4]?;
+        ///
+        /// vec.try_extend_from_within_copy(2..)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_copy(..2)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+        ///
+        /// vec.try_extend_from_within_copy(4..8)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_copy
         use fn generic_extend_from_within_copy<{R}>(&mut self, src: R)
         where {
@@ -787,17 +824,14 @@ where
 
         /// Clones elements from `src` range to the end of the vector.
         ///
-        /// # Panics
-        ///
+        do panics
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
-        ///
-        /// # Examples
-        ///
+        impl
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, bump_vec };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump_vec![in bump; 0, 1, 2, 3, 4];
         ///
         /// vec.extend_from_within_clone(2..);
@@ -809,8 +843,24 @@ where
         /// vec.extend_from_within_clone(4..8);
         /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_clone
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 0, 1, 2, 3, 4]?;
+        ///
+        /// vec.try_extend_from_within_clone(2..)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_clone(..2)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+        ///
+        /// vec.try_extend_from_within_clone(4..8)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_clone
         use fn generic_extend_from_within_clone<{R}>(&mut self, src: R)
         where {
@@ -871,6 +921,16 @@ where
         /// assert_eq!(vec, [1, 2, 3, 0, 0]);
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_extend_zeroed(2)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize)
         where {
@@ -917,12 +977,13 @@ where
         /// [`Clone`]), use [`resize_with`].
         /// If you only need to resize to a smaller size, use [`truncate`].
         ///
-        /// # Examples
-        ///
+        /// [`resize_with`]: BumpVec::resize_with
+        /// [`truncate`]: BumpBox::truncate
+        impl
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, bump_vec };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump_vec![in bump; "hello"];
         /// vec.resize(3, "world");
         /// assert_eq!(vec, ["hello", "world", "world"]);
@@ -932,11 +993,22 @@ where
         /// vec.resize(2, 0);
         /// assert_eq!(vec, [1, 2]);
         /// ```
-        ///
-        /// [`resize_with`]: BumpVec::resize_with
-        /// [`truncate`]: BumpBox::truncate
-        impl
         for fn resize
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; "hello"]?;
+        /// vec.try_resize(3, "world")?;
+        /// assert_eq!(vec, ["hello", "world", "world"]);
+        /// drop(vec);
+        ///
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3, 4]?;
+        /// vec.try_resize(2, 0)?;
+        /// assert_eq!(vec, [1, 2]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize
         use fn generic_resize(&mut self, new_len: usize, value: T)
         where { T: Clone } in
@@ -964,12 +1036,11 @@ where
         /// you'd rather [`Clone`] a given value, use [`BumpVec::resize`]. If you
         /// want to use the [`Default`] trait to generate values, you can
         /// pass [`Default::default`] as the second argument.
-        ///
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, bump_vec };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump_vec![in bump; 1, 2, 3];
         /// vec.resize_with(5, Default::default);
         /// assert_eq!(vec, [1, 2, 3, 0, 0]);
@@ -980,8 +1051,23 @@ where
         /// vec.resize_with(4, || { p *= 2; p });
         /// assert_eq!(vec, [2, 4, 8, 16]);
         /// ```
-        impl
         for fn resize_with
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_resize_with(5, Default::default);
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// drop(vec);
+        ///
+        /// let mut vec = bump_vec![try in bump]?;
+        /// let mut p = 1;
+        /// vec.try_resize_with(4, || { p *= 2; p })?;
+        /// assert_eq!(vec, [2, 4, 8, 16]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_with
         use fn generic_resize_with<{F}>(&mut self, new_len: usize, f: F)
         where {
@@ -1007,7 +1093,6 @@ where
         /// ```
         /// # use bump_scope::{ Bump, bump_vec };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump_vec![in bump; 1, 2, 3];
         /// vec.resize_zeroed(5);
         /// assert_eq!(vec, [1, 2, 3, 0, 0]);
@@ -1017,6 +1102,20 @@ where
         /// assert_eq!(vec, [1, 2]);
         /// ```
         for fn resize_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_resize_zeroed(5)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        ///
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_resize_zeroed(2)?;
+        /// assert_eq!(vec, [1, 2]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_zeroed
         use fn generic_resize_zeroed(&mut self, new_len: usize)
         where {
@@ -1033,6 +1132,7 @@ where
         }
 
         /// Moves all the elements of `other` into `self`, leaving `other` empty.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, bump_vec };
@@ -1045,8 +1145,21 @@ where
         /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
         /// assert_eq!(slice, []);
         /// ```
-        impl
         for fn append
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, bump_vec };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// // needs a scope because of lifetime shenanigans
+        /// let bump = bump.as_scope();
+        /// let mut slice = bump.try_alloc_slice_copy(&[4, 5, 6])?;
+        /// let mut vec = bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_append(&mut slice)?;
+        /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
+        /// assert_eq!(slice, []);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_append
         use fn generic_append(&mut self, other: &mut BumpBox<[T]>) {
             unsafe {
@@ -1422,7 +1535,6 @@ where
     /// ```
     /// # use bump_scope::{ Bump, bump_vec };
     /// # let bump: Bump = Bump::new();
-    /// #
     /// let mut v = bump_vec![in bump; 1, 2, 3];
     /// let u = bump.alloc_iter(v.drain(1..));
     /// assert_eq!(v, [1]);
diff --git a/src/fixed_bump_string.rs b/src/fixed_bump_string.rs
index e764f0a..06801da 100644
--- a/src/fixed_bump_string.rs
+++ b/src/fixed_bump_string.rs
@@ -331,11 +331,11 @@ impl<'a> FixedBumpString<'a> {
         do panics
         /// Panics if `idx` is larger than the `String`'s length, or if it does not
         /// lie on a [`char`] boundary.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, FixedBumpString };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut s = bump.alloc_fixed_string(3);
         ///
         /// s.insert(0, 'f');
@@ -344,8 +344,21 @@ impl<'a> FixedBumpString<'a> {
         ///
         /// assert_eq!("foo", s);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, FixedBumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut s = bump.try_alloc_fixed_string(3)?;
+        ///
+        /// s.try_insert(0, 'f')?;
+        /// s.try_insert(1, 'o')?;
+        /// s.try_insert(2, 'o')?;
+        ///
+        /// assert_eq!("foo", s);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, idx: usize, ch: char) {
             assert!(self.is_char_boundary(idx));
@@ -364,11 +377,11 @@ impl<'a> FixedBumpString<'a> {
         do panics
         /// Panics if `idx` is larger than the `FixedBumpString`'s length, or if it does not
         /// lie on a [`char`] boundary.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, FixedBumpString };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut s = bump.alloc_fixed_string(6);
         /// s.push_str("bar");
         ///
@@ -376,8 +389,20 @@ impl<'a> FixedBumpString<'a> {
         ///
         /// assert_eq!("foobar", s);
         /// ```
-        impl
         for fn insert_str
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, FixedBumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut s = bump.try_alloc_fixed_string(6)?;
+        /// s.try_push_str("bar")?;
+        ///
+        /// s.try_insert_str(0, "foo")?;
+        ///
+        /// assert_eq!("foobar", s);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert_str
         use fn generic_insert_str(&mut self, idx: usize, string: &str) {
             assert!(self.is_char_boundary(idx));
@@ -391,11 +416,11 @@ impl<'a> FixedBumpString<'a> {
         do panics
         /// Panics if the starting point or end point do not lie on a [`char`]
         /// boundary, or if they're out of bounds.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, FixedBumpString };
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut string = bump.alloc_fixed_string(14);
         /// string.push_str("abcde");
         ///
@@ -408,8 +433,25 @@ impl<'a> FixedBumpString<'a> {
         /// string.extend_from_within(4..8);
         /// assert_eq!(string, "abcdecdeabecde");
         /// ```
-        impl
         for fn extend_from_within
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, FixedBumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut string = bump.try_alloc_fixed_string(14)?;
+        /// string.try_push_str("abcde")?;
+        ///
+        /// string.try_extend_from_within(2..)?;
+        /// assert_eq!(string, "abcdecde");
+        ///
+        /// string.try_extend_from_within(..2)?;
+        /// assert_eq!(string, "abcdecdeab");
+        ///
+        /// string.try_extend_from_within(4..8)?;
+        /// assert_eq!(string, "abcdecdeabecde");
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within
         use fn generic_extend_from_within<{R}>(&mut self, src: R)
         where {
@@ -435,6 +477,17 @@ impl<'a> FixedBumpString<'a> {
         /// assert_eq!(string, "What?\0\0\0");
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, FixedBumpString };
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut string = bump.try_alloc_fixed_string(8)?;
+        /// string.try_push_str("What?")?;
+        /// string.try_extend_zeroed(3)?;
+        /// assert_eq!(string, "What?\0\0\0");
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize) {
             self.vec.generic_reserve(additional)?;
diff --git a/src/fixed_bump_vec.rs b/src/fixed_bump_vec.rs
index 19a15fa..70c9b9f 100644
--- a/src/fixed_bump_vec.rs
+++ b/src/fixed_bump_vec.rs
@@ -378,8 +378,7 @@ impl<'a, T> FixedBumpVec<'a, T> {
 
         /// Appends an element to the back of a collection.
         impl
-        /// # Examples
-        ///
+        do examples
         /// ```
         /// # use bump_scope::{ mut_bump_vec, Bump };
         /// # let mut bump: Bump = Bump::new();
@@ -389,6 +388,17 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// assert_eq!(vec, [1, 2, 3]);
         /// ```
         for fn push
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ mut_bump_vec, Bump };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(3)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2])?;
+        /// vec.try_push(3)?;
+        /// assert_eq!(vec, [1, 2, 3]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_push
         use fn generic_push(&mut self, value: T) {
             self.generic_push_with(|| value)
@@ -409,6 +419,7 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// Inserts an element at position `index` within the vector, shifting all elements after it to the right.
         do panics
         /// Panics if `index > len`.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ mut_bump_vec, Bump, FixedBumpVec };
@@ -420,8 +431,20 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// vec.insert(4, 5);
         /// assert_eq!(vec, [1, 4, 2, 3, 5]);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ mut_bump_vec, Bump, FixedBumpVec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(5)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2, 3])?;
+        /// vec.try_insert(1, 4)?;
+        /// assert_eq!(vec, [1, 4, 2, 3]);
+        /// vec.try_insert(4, 5)?;
+        /// assert_eq!(vec, [1, 4, 2, 3, 5]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, index: usize, element: T) {
             #[cold]
@@ -522,11 +545,11 @@ impl<'a, T> FixedBumpVec<'a, T> {
         do panics
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump.alloc_fixed_vec(100);
         /// vec.extend_from_slice_copy(&[0, 1, 2, 3, 4]);
         ///
@@ -539,8 +562,25 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// vec.extend_from_within_copy(4..8);
         /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_copy
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(100)?;
+        /// vec.try_extend_from_slice_copy(&[0, 1, 2, 3, 4])?;
+        ///
+        /// vec.try_extend_from_within_copy(2..)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_copy(..2)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+        ///
+        /// vec.try_extend_from_within_copy(4..8)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_copy
         use fn generic_extend_from_within_copy<{R}>(&mut self, src: R)
         where {
@@ -572,13 +612,11 @@ impl<'a, T> FixedBumpVec<'a, T> {
         ///
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
-        ///
-        /// # Examples
-        ///
+        impl
+        do examples
         /// ```
         /// # use bump_scope::Bump;
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump.alloc_fixed_vec(14);
         /// vec.extend_from_slice_copy(&[0, 1, 2, 3, 4]);
         ///
@@ -591,8 +629,25 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// vec.extend_from_within_clone(4..8);
         /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_clone
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::Bump;
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(14)?;
+        /// vec.try_extend_from_slice_copy(&[0, 1, 2, 3, 4])?;
+        ///
+        /// vec.try_extend_from_within_clone(2..)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_clone(..2)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+        ///
+        /// vec.try_extend_from_within_clone(4..8)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_clone
         use fn generic_extend_from_within_clone<{R}>(&mut self, src: R)
         where {
@@ -654,6 +709,17 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// assert_eq!(vec, [1, 2, 3, 0, 0]);
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::Bump;
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(5)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2, 3])?;
+        /// vec.try_extend_zeroed(2)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize)
         where {
@@ -701,11 +767,13 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// [`Clone`]), use [`resize_with`].
         /// If you only need to resize to a smaller size, use [`truncate`].
         ///
-        /// # Examples
+        /// [`resize_with`]: FixedBumpVec::resize_with
+        /// [`truncate`]: BumpBox::truncate
+        impl
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump.alloc_fixed_vec(10);
         /// vec.extend_from_slice_copy(&["hello"]);
         /// vec.resize(3, "world");
@@ -717,11 +785,24 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// vec.resize(2, 0);
         /// assert_eq!(vec, [1, 2]);
         /// ```
-        ///
-        /// [`resize_with`]: FixedBumpVec::resize_with
-        /// [`truncate`]: BumpBox::truncate
-        impl
         for fn resize
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(10)?;
+        /// vec.try_extend_from_slice_copy(&["hello"])?;
+        /// vec.try_resize(3, "world")?;
+        /// assert_eq!(vec, ["hello", "world", "world"]);
+        /// drop(vec);
+        ///
+        /// let mut vec = bump.try_alloc_fixed_vec(10)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2, 3, 4])?;
+        /// vec.try_resize(2, 0)?;
+        /// assert_eq!(vec, [1, 2]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize
         use fn generic_resize(&mut self, new_len: usize, value: T)
         where { T: Clone } in
@@ -749,12 +830,11 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// you'd rather [`Clone`] a given value, use [`FixedBumpVec::resize`]. If you
         /// want to use the [`Default`] trait to generate values, you can
         /// pass [`Default::default`] as the second argument.
-        ///
+        impl
         do examples
         /// ```
         /// # use bump_scope::Bump;
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump.alloc_fixed_vec(5);
         /// vec.extend_from_slice_copy(&[1, 2, 3]);
         /// vec.resize_with(5, Default::default);
@@ -766,8 +846,24 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// vec.resize_with(4, || { p *= 2; p });
         /// assert_eq!(vec, [2, 4, 8, 16]);
         /// ```
-        impl
         for fn resize_with
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::Bump;
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(5)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2, 3])?;
+        /// vec.try_resize_with(5, Default::default)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// drop(vec);
+        ///
+        /// let mut vec = bump.try_alloc_fixed_vec(4)?;
+        /// let mut p = 1;
+        /// vec.try_resize_with(4, || { p *= 2; p })?;
+        /// assert_eq!(vec, [2, 4, 8, 16]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_with
         use fn generic_resize_with<{F}>(&mut self, new_len: usize, f: F)
         where {
@@ -793,7 +889,6 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// ```
         /// # use bump_scope::Bump;
         /// # let bump: Bump = Bump::new();
-        /// #
         /// let mut vec = bump.alloc_fixed_vec(5);
         /// vec.extend_from_slice_copy(&[1, 2, 3]);
         /// vec.resize_zeroed(5);
@@ -805,6 +900,22 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// assert_eq!(vec, [1, 2]);
         /// ```
         for fn resize_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::Bump;
+        /// # let bump: Bump = Bump::try_new()?;
+        /// let mut vec = bump.try_alloc_fixed_vec(5)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2, 3])?;
+        /// vec.try_resize_zeroed(5)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        ///
+        /// let mut vec = bump.try_alloc_fixed_vec(5)?;
+        /// vec.try_extend_from_slice_copy(&[1, 2, 3])?;
+        /// vec.try_resize_zeroed(2)?;
+        /// assert_eq!(vec, [1, 2]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_zeroed
         use fn generic_resize_zeroed(&mut self, new_len: usize)
         where {
@@ -821,6 +932,7 @@ impl<'a, T> FixedBumpVec<'a, T> {
         }
 
         /// Moves all the elements of `other` into `self`, leaving `other` empty.
+        impl
         do examples
         /// ```
         /// # use bump_scope::Bump;
@@ -836,8 +948,24 @@ impl<'a, T> FixedBumpVec<'a, T> {
         /// assert_eq!(a, [1, 2, 3, 4, 5, 6]);
         /// assert_eq!(b, []);
         /// ```
-        impl
         for fn append
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::Bump;
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// // needs a scope because of lifetime shenanigans
+        /// let bump = bump.as_mut_scope();
+        /// let mut a = bump.try_alloc_fixed_vec(6)?;
+        /// a.try_extend_from_slice_copy(&[1, 2, 3])?;
+        ///
+        /// let mut b = bump.try_alloc_slice_copy(&[4, 5, 6])?;
+        ///
+        /// a.try_append(&mut b)?;
+        /// assert_eq!(a, [1, 2, 3, 4, 5, 6]);
+        /// assert_eq!(b, []);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_append
         use fn generic_append(&mut self, other: &mut BumpBox<[T]>) {
             unsafe {
diff --git a/src/lib.rs b/src/lib.rs
index a246be9..a188dc2 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1759,7 +1759,6 @@ define_alloc_methods! {
 
     /// Allocates memory as described by the given `Layout`.
     impl
-    do examples
     for fn alloc_layout
     for fn try_alloc_layout
     use fn generic_alloc_layout(&self, layout: Layout) -> NonNull<u8> | NonNull<u8>;
diff --git a/src/mut_bump_string.rs b/src/mut_bump_string.rs
index 6e2720e..9b86bba 100644
--- a/src/mut_bump_string.rs
+++ b/src/mut_bump_string.rs
@@ -441,11 +441,11 @@ where
         do panics
         /// Panics if `idx` is larger than the `String`'s length, or if it does not
         /// lie on a [`char`] boundary.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, MutBumpString };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut s = MutBumpString::with_capacity_in(3, &mut bump);
         ///
         /// s.insert(0, 'f');
@@ -454,8 +454,21 @@ where
         ///
         /// assert_eq!("foo", s);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, MutBumpString };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut s = MutBumpString::try_with_capacity_in(3, &mut bump)?;
+        ///
+        /// s.try_insert(0, 'f')?;
+        /// s.try_insert(1, 'o')?;
+        /// s.try_insert(2, 'o')?;
+        ///
+        /// assert_eq!("foo", s);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, idx: usize, ch: char) {
             assert!(self.is_char_boundary(idx));
@@ -474,19 +487,30 @@ where
         do panics
         /// Panics if `idx` is larger than the `MutBumpString`'s length, or if it does not
         /// lie on a [`char`] boundary.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, MutBumpString };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut s = MutBumpString::from_str_in("bar", &mut bump);
         ///
         /// s.insert_str(0, "foo");
         ///
         /// assert_eq!("foobar", s);
         /// ```
-        impl
         for fn insert_str
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, MutBumpString };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut s = MutBumpString::try_from_str_in("bar", &mut bump)?;
+        ///
+        /// s.try_insert_str(0, "foo")?;
+        ///
+        /// assert_eq!("foobar", s);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert_str
         use fn generic_insert_str(&mut self, idx: usize, string: &str) {
             assert!(self.is_char_boundary(idx));
@@ -500,11 +524,11 @@ where
         do panics
         /// Panics if the starting point or end point do not lie on a [`char`]
         /// boundary, or if they're out of bounds.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, MutBumpString };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut string = MutBumpString::from_str_in("abcde", &mut bump);
         ///
         /// string.extend_from_within(2..);
@@ -516,8 +540,24 @@ where
         /// string.extend_from_within(4..8);
         /// assert_eq!(string, "abcdecdeabecde");
         /// ```
-        impl
         for fn extend_from_within
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, MutBumpString };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut string = MutBumpString::try_from_str_in("abcde", &mut bump)?;
+        ///
+        /// string.try_extend_from_within(2..)?;
+        /// assert_eq!(string, "abcdecde");
+        ///
+        /// string.try_extend_from_within(..2)?;
+        /// assert_eq!(string, "abcdecdeab");
+        ///
+        /// string.try_extend_from_within(4..8)?;
+        /// assert_eq!(string, "abcdecdeabecde");
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within
         use fn generic_extend_from_within<{R}>(&mut self, src: R)
         where {
@@ -542,6 +582,16 @@ where
         /// assert_eq!(string, "What?\0\0\0");
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, MutBumpString };
+        /// # let mut bump: Bump = Bump::new();
+        /// let mut string = MutBumpString::try_from_str_in("What?", &mut bump)?;
+        /// string.try_extend_zeroed(3)?;
+        /// assert_eq!(string, "What?\0\0\0");
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize) {
             self.generic_reserve(additional)?;
diff --git a/src/mut_bump_vec.rs b/src/mut_bump_vec.rs
index 770c53d..09bf055 100644
--- a/src/mut_bump_vec.rs
+++ b/src/mut_bump_vec.rs
@@ -530,8 +530,7 @@ where
     error_behavior_generic_methods_allocation_failure! {
         /// Appends an element to the back of a collection.
         impl
-        /// # Examples
-        ///
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
@@ -540,6 +539,16 @@ where
         /// assert_eq!(vec, [1, 2, 3]);
         /// ```
         for fn push
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; 1, 2]?;
+        /// vec.try_push(3)?;
+        /// assert_eq!(vec, [1, 2, 3]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_push
         use fn generic_push(&mut self, value: T) {
             self.generic_push_with(|| value)
@@ -560,6 +569,7 @@ where
         /// Inserts an element at position `index` within the vector, shifting all elements after it to the right.
         do panics
         /// Panics if `index > len`.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
@@ -570,8 +580,19 @@ where
         /// vec.insert(4, 5);
         /// assert_eq!(vec, [1, 4, 2, 3, 5]);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_insert(1, 4)?;
+        /// assert_eq!(vec, [1, 4, 2, 3]);
+        /// vec.try_insert(4, 5)?;
+        /// assert_eq!(vec, [1, 4, 2, 3, 5]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, index: usize, element: T) {
             #[cold]
@@ -672,11 +693,11 @@ where
         do panics
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec![in bump; 0, 1, 2, 3, 4];
         ///
         /// vec.extend_from_within_copy(2..);
@@ -688,8 +709,24 @@ where
         /// vec.extend_from_within_copy(4..8);
         /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_copy
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; 0, 1, 2, 3, 4]?;
+        ///
+        /// vec.try_extend_from_within_copy(2..)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_copy(..2)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+        ///
+        /// vec.try_extend_from_within_copy(4..8)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_copy
         use fn generic_extend_from_within_copy<{R}>(&mut self, src: R)
         where {
@@ -721,13 +758,11 @@ where
         ///
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
-        ///
-        /// # Examples
-        ///
+        impl
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec![in bump; 0, 1, 2, 3, 4];
         ///
         /// vec.extend_from_within_clone(2..);
@@ -739,8 +774,24 @@ where
         /// vec.extend_from_within_clone(4..8);
         /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_clone
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; 0, 1, 2, 3, 4]?;
+        ///
+        /// vec.try_extend_from_within_clone(2..)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_clone(..2)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+        ///
+        /// vec.try_extend_from_within_clone(4..8)?;
+        /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_clone
         use fn generic_extend_from_within_clone<{R}>(&mut self, src: R)
         where {
@@ -801,6 +852,16 @@ where
         /// assert_eq!(vec, [1, 2, 3, 0, 0]);
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_extend_zeroed(2)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize)
         where {
@@ -847,12 +908,13 @@ where
         /// [`Clone`]), use [`resize_with`].
         /// If you only need to resize to a smaller size, use [`truncate`].
         ///
-        /// # Examples
-        ///
+        /// [`resize_with`]: MutBumpVec::resize_with
+        /// [`truncate`]: BumpBox::truncate
+        impl
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec![in bump; "hello"];
         /// vec.resize(3, "world");
         /// assert_eq!(vec, ["hello", "world", "world"]);
@@ -862,11 +924,22 @@ where
         /// vec.resize(2, 0);
         /// assert_eq!(vec, [1, 2]);
         /// ```
-        ///
-        /// [`resize_with`]: MutBumpVec::resize_with
-        /// [`truncate`]: BumpBox::truncate
-        impl
         for fn resize
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; "hello"]?;
+        /// vec.try_resize(3, "world")?;
+        /// assert_eq!(vec, ["hello", "world", "world"]);
+        /// drop(vec);
+        ///
+        /// let mut vec = mut_bump_vec![try in bump; 1, 2, 3, 4]?;
+        /// vec.try_resize(2, 0)?;
+        /// assert_eq!(vec, [1, 2]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize
         use fn generic_resize(&mut self, new_len: usize, value: T)
         where { T: Clone } in
@@ -894,12 +967,11 @@ where
         /// you'd rather [`Clone`] a given value, use [`MutBumpVec::resize`]. If you
         /// want to use the [`Default`] trait to generate values, you can
         /// pass [`Default::default`] as the second argument.
-        ///
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec![in bump; 1, 2, 3];
         /// vec.resize_with(5, Default::default);
         /// assert_eq!(vec, [1, 2, 3, 0, 0]);
@@ -910,8 +982,23 @@ where
         /// vec.resize_with(4, || { p *= 2; p });
         /// assert_eq!(vec, [2, 4, 8, 16]);
         /// ```
-        impl
         for fn resize_with
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_resize_with(5, Default::default)?;
+        /// assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// drop(vec);
+        ///
+        /// let mut vec = mut_bump_vec![try in bump]?;
+        /// let mut p = 1;
+        /// vec.try_resize_with(4, || { p *= 2; p })?;
+        /// assert_eq!(vec, [2, 4, 8, 16]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_with
         use fn generic_resize_with<{F}>(&mut self, new_len: usize, f: F)
         where {
@@ -937,7 +1024,6 @@ where
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// {
         ///     let mut vec = mut_bump_vec![in bump; 1, 2, 3];
         ///     vec.resize_zeroed(5);
@@ -951,6 +1037,24 @@ where
         /// }
         /// ```
         for fn resize_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// {
+        ///     let mut vec = mut_bump_vec![try in bump; 1, 2, 3]?;
+        ///     vec.try_resize_zeroed(5)?;
+        ///     assert_eq!(vec, [1, 2, 3, 0, 0]);
+        /// }
+        ///
+        /// {
+        ///    let mut vec = mut_bump_vec![try in bump; 1, 2, 3]?;
+        ///    vec.try_resize_zeroed(2)?;
+        ///    assert_eq!(vec, [1, 2]);
+        /// }
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_zeroed
         use fn generic_resize_zeroed(&mut self, new_len: usize)
         where {
@@ -967,6 +1071,7 @@ where
         }
 
         /// Moves all the elements of `other` into `self`, leaving `other` empty.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec };
@@ -979,8 +1084,21 @@ where
         /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
         /// assert_eq!(slice, []);
         /// ```
-        impl
         for fn append
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// // needs a scope because of lifetime shenanigans
+        /// let bump = bump.as_mut_scope();
+        /// let mut slice = bump.try_alloc_slice_copy(&[4, 5, 6])?;
+        /// let mut vec = mut_bump_vec![try in bump; 1, 2, 3]?;
+        /// vec.try_append(&mut slice)?;
+        /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
+        /// assert_eq!(slice, []);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_append
         use fn generic_append(&mut self, other: &mut BumpBox<[T]>) {
             unsafe {
diff --git a/src/mut_bump_vec_rev.rs b/src/mut_bump_vec_rev.rs
index 4712ed3..411a7bf 100644
--- a/src/mut_bump_vec_rev.rs
+++ b/src/mut_bump_vec_rev.rs
@@ -469,7 +469,6 @@ impl<'b, 'a: 'b, T, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_
     /// ```
     /// # use bump_scope::{ Bump, MutBumpVecRev };
     /// # let mut bump: Bump = Bump::new();
-    /// #
     /// // Allocate vector big enough for 4 elements.
     /// let size = 4;
     /// let mut x = MutBumpVecRev::<i32>::with_capacity_in(size, &mut bump);
@@ -599,8 +598,7 @@ where
 
         /// Appends an element to the front of a collection.
         impl
-        /// # Examples
-        ///
+        do examples
         /// ```
         /// # use bump_scope::{ mut_bump_vec_rev, Bump };
         /// # let mut bump: Bump = Bump::new();
@@ -610,6 +608,17 @@ where
         /// # let _ = vec;
         /// ```
         for fn push
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ mut_bump_vec_rev, Bump };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; 2, 1]?;
+        /// vec.try_push(3)?;
+        /// assert_eq!(vec, [3, 2, 1]);
+        /// # let _ = vec;
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_push
         use fn generic_push(&mut self, value: T) {
             self.generic_push_with(|| value)
@@ -630,6 +639,7 @@ where
         /// Inserts an element at position `index` within the vector, shifting all elements after it to the right.
         do panics
         /// Panics if `index > len`.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ mut_bump_vec_rev, Bump };
@@ -640,8 +650,19 @@ where
         /// vec.insert(4, 5);
         /// assert_eq!(vec, [1, 4, 2, 3, 5]);
         /// ```
-        impl
         for fn insert
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ mut_bump_vec_rev, Bump };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; 1, 2, 3]?;
+        /// vec.try_insert(1, 4)?;
+        /// assert_eq!(vec, [1, 4, 2, 3]);
+        /// vec.try_insert(4, 5)?;
+        /// assert_eq!(vec, [1, 4, 2, 3, 5]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_insert
         use fn generic_insert(&mut self, index: usize, element: T) {
             #[cold]
@@ -729,11 +750,11 @@ where
         do panics
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec_rev };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec_rev![in bump; 0, 1, 2, 3, 4];
         ///
         /// vec.extend_from_within_copy(2..);
@@ -745,8 +766,24 @@ where
         /// vec.extend_from_within_copy(4..8);
         /// assert_eq!(vec, [4, 0, 1, 2, 2, 3, 2, 3, 4, 0, 1, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_copy
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec_rev };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; 0, 1, 2, 3, 4]?;
+        ///
+        /// vec.try_extend_from_within_copy(2..)?;
+        /// assert_eq!(vec, [2, 3, 4, 0, 1, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_copy(..2)?;
+        /// assert_eq!(vec, [2, 3, 2, 3, 4, 0, 1, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_copy(4..8)?;
+        /// assert_eq!(vec, [4, 0, 1, 2, 2, 3, 2, 3, 4, 0, 1, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_copy
         use fn generic_extend_from_within_copy<{R}>(&mut self, src: R)
         where {
@@ -785,6 +822,16 @@ where
         /// assert_eq!(vec, [0, 0, 1, 2, 3]);
         /// ```
         for fn extend_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec_rev };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; 1, 2, 3]?;
+        /// vec.try_extend_zeroed(2)?;
+        /// assert_eq!(vec, [0, 0, 1, 2, 3]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_zeroed
         use fn generic_extend_zeroed(&mut self, additional: usize)
         where {
@@ -828,13 +875,11 @@ where
         /// If you need more flexibility (or want to rely on [`Default`] instead of
         /// [`Clone`]), use [`MutBumpVecRev::resize_with`].
         /// If you only need to resize to a smaller size, use [`MutBumpVecRev::truncate`].
-        ///
-        /// # Examples
-        ///
+        impl
+        do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec_rev };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec_rev![in bump; "hello"];
         /// vec.resize(3, "world");
         /// assert_eq!(vec, ["world", "world", "hello"]);
@@ -844,8 +889,22 @@ where
         /// vec.resize(2, 0);
         /// assert_eq!(vec, [3, 4]);
         /// ```
-        impl
         for fn resize
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec_rev };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; "hello"]?;
+        /// vec.try_resize(3, "world")?;
+        /// assert_eq!(vec, ["world", "world", "hello"]);
+        /// drop(vec);
+        ///
+        /// let mut vec = mut_bump_vec_rev![try in bump; 1, 2, 3, 4]?;
+        /// vec.try_resize(2, 0)?;
+        /// assert_eq!(vec, [3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize
         use fn generic_resize(&mut self, new_len: usize, value: T)
         where { T: Clone } in
@@ -873,12 +932,11 @@ where
         /// you'd rather [`Clone`] a given value, use [`MutBumpVecRev::resize`]. If you
         /// want to use the [`Default`] trait to generate values, you can
         /// pass [`Default::default`] as the second argument.
-        ///
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec_rev };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec_rev![in bump; 1, 2, 3];
         /// vec.resize_with(5, Default::default);
         /// assert_eq!(vec, [0, 0, 1, 2, 3]);
@@ -889,8 +947,23 @@ where
         /// vec.resize_with(4, || { p *= 2; p });
         /// assert_eq!(vec, [16, 8, 4, 2]);
         /// ```
-        impl
         for fn resize_with
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec_rev };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; 1, 2, 3]?;
+        /// vec.try_resize_with(5, Default::default)?;
+        /// assert_eq!(vec, [0, 0, 1, 2, 3]);
+        /// drop(vec);
+        ///
+        /// let mut vec = mut_bump_vec_rev![try in bump]?;
+        /// let mut p = 1;
+        /// vec.try_resize_with(4, || { p *= 2; p })?;
+        /// assert_eq!(vec, [16, 8, 4, 2]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_with
         use fn generic_resize_with<{F}>(&mut self, new_len: usize, f: F)
         where {
@@ -916,7 +989,6 @@ where
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec_rev };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// {
         ///     let mut vec = mut_bump_vec_rev![in bump; 1, 2, 3];
         ///     vec.resize_zeroed(5);
@@ -930,6 +1002,24 @@ where
         /// }
         /// ```
         for fn resize_zeroed
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec_rev };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// {
+        ///     let mut vec = mut_bump_vec_rev![try in bump; 1, 2, 3]?;
+        ///     vec.try_resize_zeroed(5)?;
+        ///     assert_eq!(vec, [0, 0, 1, 2, 3]);
+        /// }
+        ///
+        /// {
+        ///     let mut vec = mut_bump_vec_rev![try in bump; 1, 2, 3]?;
+        ///     vec.try_resize_zeroed(2)?;
+        ///     assert_eq!(vec, [2, 3]);
+        /// }
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_resize_zeroed
         use fn generic_resize_zeroed(&mut self, new_len: usize)
         where {
@@ -1293,11 +1383,11 @@ where
         do panics
         /// Panics if the starting point is greater than the end point or if
         /// the end point is greater than the length of the vector.
+        impl
         do examples
         /// ```
         /// # use bump_scope::{ Bump, mut_bump_vec_rev };
         /// # let mut bump: Bump = Bump::new();
-        /// #
         /// let mut vec = mut_bump_vec_rev![in bump; 0, 1, 2, 3, 4];
         ///
         /// vec.extend_from_within_clone(2..);
@@ -1309,8 +1399,24 @@ where
         /// vec.extend_from_within_clone(4..8);
         /// assert_eq!(vec, [4, 0, 1, 2, 2, 3, 2, 3, 4, 0, 1, 2, 3, 4]);
         /// ```
-        impl
         for fn extend_from_within_clone
+        do examples
+        /// ```
+        /// # #![cfg_attr(feature = "nightly-allocator-api", feature(allocator_api))]
+        /// # use bump_scope::{ Bump, mut_bump_vec_rev };
+        /// # let mut bump: Bump = Bump::try_new()?;
+        /// let mut vec = mut_bump_vec_rev![try in bump; 0, 1, 2, 3, 4]?;
+        ///
+        /// vec.try_extend_from_within_clone(2..)?;
+        /// assert_eq!(vec, [2, 3, 4, 0, 1, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_clone(..2)?;
+        /// assert_eq!(vec, [2, 3, 2, 3, 4, 0, 1, 2, 3, 4]);
+        ///
+        /// vec.try_extend_from_within_clone(4..8)?;
+        /// assert_eq!(vec, [4, 0, 1, 2, 2, 3, 2, 3, 4, 0, 1, 2, 3, 4]);
+        /// # Ok::<(), bump_scope::allocator_api2::alloc::AllocError>(())
+        /// ```
         for fn try_extend_from_within_clone
         use fn generic_extend_from_within_clone<{R}>(&mut self, src: R)
         where {