doc: fix docs not correctly adapted to this crate

src/bump_box.rs

@@ -438,7 +438,7 @@ impl<'a> BumpBox<'a, str> {
     ///
     /// This function is unsafe because the returned `&mut BumpBox<[u8]>` allows writing
     /// bytes which are not valid UTF-8. If this constraint is violated, using
-    /// the original `BumpBox<str>` after dropping the `&mut Vec` may violate memory
+    /// the original `BumpBox<str>` after dropping the `&mut BumpBox<[u8]>` may violate memory
     /// safety, as `BumpBox<str>`s must be valid UTF-8.
     #[must_use]
     #[inline(always)]

src/bump_string.rs

@@ -84,7 +84,7 @@ macro_rules! bump_string_declaration {
         /// let hello = BumpString::from_str_in("Hello, world!", &bump);
         /// ```
         ///
-        /// You can append a [`char`] to a `String` with the [`push`] method, and
+        /// You can append a [`char`] to a string with the [`push`] method, and
         /// append a [`&str`] with the [`push_str`] method:
         ///
         /// ```
@@ -857,9 +857,9 @@ where
     ///
     /// # Safety
     ///
-    /// This function is unsafe because the returned `&mut Vec` allows writing
+    /// This function is unsafe because the returned `&mut BumpVec<u8>` allows writing
     /// bytes which are not valid UTF-8. If this constraint is violated, using
-    /// the original `BumpString` after dropping the `&mut Vec` may violate memory
+    /// the original `BumpString` after dropping the `&mut BumpVec<u8>` may violate memory
     /// safety, as `BumpString`s must be valid UTF-8.
     #[must_use]
     #[inline(always)]
@@ -954,7 +954,7 @@ where
         /// This is an *O*(*n*) operation as it requires copying every element in the
         /// buffer.
         do panics
-        /// Panics if `idx` is larger than the `String`'s length, or if it does not
+        /// Panics if `idx` is larger than the string's length, or if it does not
         /// lie on a [`char`] boundary.
         impl
         do examples
@@ -1825,7 +1825,7 @@ where
 /// // `a` is moved and can no longer be used here.
 /// ```
 ///
-/// If you want to keep using the first `String`, you can clone it and append to the clone instead:
+/// If you want to keep using the first `BumpString`, you can clone it and append to the clone instead:
 ///
 /// ```
 /// # use bump_scope::{ Bump, BumpString };

src/bump_vec.rs

@@ -1551,6 +1551,8 @@ where
     /// # Safety
     ///
     /// - `len` must be less than or equal to `self.capacity()`
+    ///
+    /// [`reserve`]: Self::reserve
     #[cfg(not(no_global_oom_handling))]
     #[inline(always)]
     pub(crate) unsafe fn buf_reserve(&mut self, len: usize, additional: usize) {
@@ -1617,11 +1619,14 @@ where
 
     /// Like [`reserve`] but allows you to provide a different `len`.
     ///
-    /// This is only used for [`buf_reserve`](Self::buf_reserve), read its documentation for more.
+    /// This is only used for [`buf_reserve`], read its documentation for more.
     ///
     /// # Safety
     ///
     /// - `len` must be less than or equal to `self.capacity()`
+    ///
+    /// [`reserve`]: Self::reserve
+    /// [`buf_reserve`]: Self::buf_reserve
     #[cold]
     #[inline(never)]
     #[cfg(not(no_global_oom_handling))]

src/bump_vec/drain.rs

@@ -16,15 +16,15 @@ macro_rules! drain_declaration {
     ($($allocator_parameter:tt)*) => {
         /// A draining iterator for `BumpVec<T>`.
         ///
-        /// This `struct` is created by [`Vec::drain`].
-        /// See its documentation for more.
+        /// This `struct` is not directly created by any method.
+        /// It is an implementation detail of `Splice`.
         ///
-        /// # Example
+        /// The implementation of `drain` does not need a pointer to the whole `BumpVec`
+        /// (and all the generic parameters that come with it).
+        /// That's why we return `owned_slice::Drain` from `BumpVec::drain`.
         ///
-        /// ```
-        /// let mut v = vec![0, 1, 2];
-        /// let iter: std::vec::Drain<_> = v.drain(..);
-        /// ```
+        /// However just like the standard library we use a `Drain` implementation to implement
+        /// `Splice`. For this particular case we *do* need a pointer to `BumpVec`.
         pub struct Drain<
             'a,
             T: 'a,
@@ -93,7 +93,7 @@ where
         unsafe { self.vec.as_ref().allocator() }
     }
 
-    /// Keep unyielded elements in the source `Vec`.
+    /// Keep unyielded elements in the source vector.
     ///
     /// # Examples
     ///
@@ -214,7 +214,7 @@ where
 {
     #[inline]
     fn drop(&mut self) {
-        /// Moves back the un-`Drain`ed elements to restore the original `Vec`.
+        /// Moves back the un-`Drain`ed elements to restore the original vector.
         struct DropGuard<'r, 'a, T, A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool>(
             &'r mut Drain<'a, T, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED>,
         )
@@ -253,7 +253,7 @@ where
 
         if T::IS_ZST {
             // ZSTs have no identity, so we don't need to move them around, we only need to drop the correct amount.
-            // this can be achieved by manipulating the Vec length instead of moving values out from `iter`.
+            // this can be achieved by manipulating the vector length instead of moving values out from `iter`.
             unsafe {
                 let vec = vec.as_mut();
                 let old_len = vec.len();

src/fixed_bump_string.rs

@@ -460,9 +460,9 @@ impl<'a> FixedBumpString<'a> {
     ///
     /// # Safety
     ///
-    /// This function is unsafe because the returned `&mut Vec` allows writing
+    /// This function is unsafe because the returned `&mut FixedBumpVec<u8>` allows writing
     /// bytes which are not valid UTF-8. If this constraint is violated, using
-    /// the original `FixedBumpString` after dropping the `&mut Vec` may violate memory
+    /// the original `FixedBumpString` after dropping the `&mut FixedBumpVec<u8>` may violate memory
     /// safety, as `FixedBumpString`s must be valid UTF-8.
     #[must_use]
     #[inline(always)]
@@ -556,7 +556,7 @@ impl FixedBumpString<'_> {
         /// This is an *O*(*n*) operation as it requires copying every element in the
         /// buffer.
         do panics
-        /// Panics if `idx` is larger than the `String`'s length, or if it does not
+        /// Panics if `idx` is larger than the string's length, or if it does not
         /// lie on a [`char`] boundary.
         impl
         do examples

src/from_utf16_error.rs

@@ -1,20 +1,25 @@
 use core::fmt;
 
-/// A possible error value when converting a `String` from a UTF-16 byte slice.
+/// A possible error value when converting a string from a UTF-16 byte slice.
 ///
-/// This type is the error type for the [`from_utf16`] method on [`String`].
-///
-/// [`from_utf16`]: String::from_utf16
+/// This type is the error type for the `from_utf16_in` method on
+/// <code>([Mut])[BumpString]</code>.
 ///
 /// # Examples
 ///
 /// ```
+/// # use bump_scope::{ Bump, BumpString };
+/// # let bump: Bump = Bump::new();
+///
 /// // 𝄞mu<invalid>ic
 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
 ///           0xD800, 0x0069, 0x0063];
 ///
-/// assert!(String::from_utf16(v).is_err());
+/// assert!(BumpString::from_utf16_in(v, &bump).is_err());
 /// ```
+///
+/// [Mut]: crate::MutBumpString::from_utf16_in
+/// [BumpString]: crate::BumpString::from_utf16_in
 #[derive(Debug)]
 pub struct FromUtf16Error(pub(crate) ());
 

src/mut_bump_string.rs

@@ -85,7 +85,7 @@ macro_rules! mut_bump_string_declaration {
         /// # let _ = hello;
         /// ```
         ///
-        /// You can append a [`char`] to a `String` with the [`push`] method, and
+        /// You can append a [`char`] to a string with the [`push`] method, and
         /// append a [`&str`] with the [`push_str`] method:
         ///
         /// ```
@@ -665,14 +665,14 @@ impl<'b, 'a: 'b, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCA
         self.fixed.truncate(new_len);
     }
 
-    /// Removes a [`char`] from this `String` at a byte position and returns it.
+    /// Removes a [`char`] from this string at a byte position and returns it.
     ///
     /// This is an *O*(*n*) operation, as it requires copying every element in the
     /// buffer.
     ///
     /// # Panics
     ///
-    /// Panics if `idx` is larger than or equal to the `String`'s length,
+    /// Panics if `idx` is larger than or equal to the string's length,
     /// or if it does not lie on a [`char`] boundary.
     ///
     /// # Examples
@@ -799,9 +799,9 @@ impl<'b, 'a: 'b, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCA
     ///
     /// # Safety
     ///
-    /// This function is unsafe because the returned `&mut Vec` allows writing
+    /// This function is unsafe because the returned `&mut MutBumpVec<u8>` allows writing
     /// bytes which are not valid UTF-8. If this constraint is violated, using
-    /// the original `MutBumpString` after dropping the `&mut Vec` may violate memory
+    /// the original `MutBumpString` after dropping the `&mut MutBumpVec<u8>` may violate memory
     /// safety, as `MutBumpString`s must be valid UTF-8.
     #[must_use]
     #[inline(always)]
@@ -896,7 +896,7 @@ where
         /// This is an *O*(*n*) operation as it requires copying every element in the
         /// buffer.
         do panics
-        /// Panics if `idx` is larger than the `String`'s length, or if it does not
+        /// Panics if `idx` is larger than the string's length, or if it does not
         /// lie on a [`char`] boundary.
         impl
         do examples

src/owned_slice/drain.rs

@@ -194,7 +194,7 @@ impl<T> DoubleEndedIterator for Drain<'_, T> {
 
 impl<T> Drop for Drain<'_, T> {
     fn drop(&mut self) {
-        /// Moves back the un-`Drain`ed elements to restore the original `Vec`.
+        /// Moves back the un-`Drain`ed elements to restore the original slice.
         struct DropGuard<'r, 'a, T>(&'r mut Drain<'a, T>);
 
         impl<T> Drop for DropGuard<'_, '_, T> {

src/owned_str/drain.rs

@@ -34,7 +34,7 @@ unsafe impl Send for Drain<'_> {}
 impl Drop for Drain<'_> {
     fn drop(&mut self) {
         unsafe {
-            // Use Vec::drain. "Reaffirm" the bounds checks to avoid
+            // Use `BumpBox::<[u8]>::drain`. "Reaffirm" the bounds checks to avoid
             // panic code being inserted again.
             let self_vec = self.string.as_mut().as_mut_bytes();
 
@@ -51,7 +51,9 @@ impl Drain<'_> {
     /// # Examples
     ///
     /// ```
-    /// let mut s = String::from("abc");
+    /// # use bump_scope::{ Bump };
+    /// # let bump: Bump = Bump::new();    ///
+    /// let mut s = bump.alloc_str("abc");
     /// let mut drain = s.drain(..);
     /// assert_eq!(drain.as_str(), "abc");
     /// let _ = drain.next().unwrap();

src/polyfill/str/lossy.rs

@@ -99,7 +99,7 @@ impl<'a> Utf8Chunk<'a> {
     /// CHARACTER`].
     ///
     /// [`valid`]: Self::valid
-    /// [`U+FFFD REPLACEMENT CHARACTER`]: crate::char::REPLACEMENT_CHARACTER
+    /// [`U+FFFD REPLACEMENT CHARACTER`]: core::char::REPLACEMENT_CHARACTER
     #[must_use]
     pub fn invalid(&self) -> &'a [u8] {
         self.invalid
@@ -152,7 +152,7 @@ impl fmt::Debug for Debug<'_> {
 /// See the [`Utf8Chunk`] type for documentation of the items yielded by this iterator.
 ///
 /// [byteslice]: slice
-/// [`from_utf8`]: super::from_utf8
+/// [`from_utf8`]: core::str::from_utf8
 ///
 /// # Examples
 ///
@@ -171,7 +171,7 @@ impl fmt::Debug for Debug<'_> {
 /// }
 /// ```
 ///
-/// [`String::from_utf8_lossy`]: ../../std/string/struct.String.html#method.from_utf8_lossy
+/// [`String::from_utf8_lossy`]: alloc::string::String::from_utf8_lossy
 #[must_use = "iterators are lazy and do nothing unless consumed"]
 #[derive(Clone)]
 pub struct Utf8Chunks<'a> {

src/tests/from_std/bump_string.rs

@@ -447,6 +447,7 @@ fn test_simple_types() {
     assert_eq!(bump_format!(in bump, "{}", BumpString::from_str_in("hi", &bump)), "hi");
 }
 
+// TODO: bump_vec!
 #[test]
 fn test_vectors() {
     let bump: Bump = Bump::new();