chore: improve docs

- fix example in README
- remove old references to 'static lifetime

README.md

@@ -26,7 +26,7 @@ let _clone = simple_greetings.clone(); // no copy
 
 let user = "John";
 let greetings = HipStr::from(format!("Hello {}", user));
-let user = greetings.slice(6..): // no copy
+let user = greetings.slice(6..); // no copy
 drop(greetings); // the slice is owned, it exists even if greetings disappear
 
 let chars = user.chars().count(); // "inherits" `&str` methods
@@ -96,7 +96,7 @@ cross test --target i686-unknown-linux-gnu          # 32-bit LE
 cross test --target x86_64-unknown-linux-gnu        # 64-bit LE
 ```
 
-NB: previously I used MIPS targets for big endian, but due to some LLVM-related
+Note: previously I used MIPS targets for big endian, but due to some LLVM-related
 issue they are not working anymore… see
 [Rust issue #113065](https://github.com/rust-lang/rust/issues/113065)
 

src/bytes.rs

@@ -54,10 +54,14 @@ where
     ///
     /// Function provided for [`Vec::new`] replacement.
     ///
-    /// # ⚠️ Warning!
+    /// # Representation
+    ///
+    /// <div class=warning>
     ///
     /// The used representation of the empty string is unspecified.
-    /// It may be *borrowed* or *inlined* but will never be allocated.
+    /// It may be _borrowed* or *inlined* but will never be allocated.
+    ///
+    /// </div>
     ///
     /// # Examples
     ///
@@ -76,6 +80,10 @@ where
     /// Creates a new inline `HipByt` by copying the given slice.
     /// The slice **must not** be too large to be inlined.
     ///
+    /// # Representation
+    ///
+    /// The created `HipByt` is _inline_.
+    ///
     /// # Panics
     ///
     /// It panics if the slice is too large.
@@ -100,6 +108,10 @@ where
     /// Creates a new inline `HipByt` by copying the given the slice.
     /// Return `None` if the given slice is too large to be inlined.
     ///
+    /// # Representation
+    ///
+    /// In case of success, the created `HipByt` is _inline_.
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -121,7 +133,18 @@ where
 
     /// Creates a new `HipByt` with the given capacity.
     ///
-    /// The underlying representation is not **normalized**.
+    /// The final capacity depends on the representation and is not guaranteed
+    /// to be exact. However, the returned `HipByt` will be able to hold at
+    /// least `capacity` bytes without reallocating or changing representation.
+    ///
+    /// # Representation
+    ///
+    /// If the capacity is less or equal to the inline capacity, the
+    /// representation will be *inline*.
+    ///
+    /// Otherwise, it will be *allocated*.
+    ///
+    /// The representation is **not normalized**.
     ///
     /// # Examples
     ///
@@ -422,7 +445,7 @@ where
     ///
     /// # Errors
     ///
-    /// Returns `Err(self)` if this `HipByt` is not a borrow.
+    /// Returns `Err(self)` if this `HipByt` is not borrowed.
     ///
     /// # Examples
     ///
@@ -1419,10 +1442,14 @@ impl<B> HipByt<'static, B>
 where
     B: Backend,
 {
-    /// Creates a new `HipByt` from a static slice without copying the slice.
+    /// Creates a new `HipByt` from a `'static` slice without copying the slice.
     ///
     /// Handy shortcut to make a `HipByt<'static, _>` out of a `&'static [u8]`.
     ///
+    /// # Representation
+    ///
+    /// The created `HipByt` is _borrowed_.
+    ///
     /// # Examples
     ///
     /// Basic usage:

src/bytes/raw/allocated.rs

@@ -237,7 +237,7 @@ impl<B: Backend> Allocated<B> {
         self.ptr.cast_mut()
     }
 
-    /// Returns a mutable slice if possible (unique non-static reference).
+    /// Returns a mutable slice if possible (unique owned reference).
     #[inline]
     pub fn as_mut_slice(&mut self) -> Option<&mut [u8]> {
         if self.is_unique() {

src/os_string.rs

@@ -109,8 +109,18 @@ where
 
     /// Creates a new `HipOsStr` with the given capacity.
     ///
-    /// The returned `HipOsStr` will be able to hold at least `capacity` bytes
-    /// without reallocating or changing representation.
+    /// The final capacity depends on the representation and is not guaranteed
+    /// to be exact. However, the returned `HipOsStr` will be able to hold at
+    /// least `capacity` bytes without reallocating or changing representation.
+    ///
+    /// # Representation
+    ///
+    /// If the capacity is less or equal to the inline capacity, the
+    /// representation will be *inline*.
+    ///
+    /// Otherwise, it will be *allocated*.
+    ///
+    /// The representation is **not normalized**.
     ///
     /// # Examples
     ///
@@ -131,9 +141,18 @@ where
         Self(HipByt::with_capacity(cap))
     }
 
-    /// Creates a new `HipOsStr` from a static os string slice without copying the slice.
+    /// Creates a new `HipOsStr` from an OS string slice without copying the
+    /// slice.
     ///
-    /// Requires only `impl AsRef<OsStr>`: it accepts `&str`, `&OsStr`, and `&Path` for instance.
+    /// Requires only `impl AsRef<OsStr>`: it accepts `&str`, `&OsStr`, and
+    /// `&Path` for instance.
+    ///
+    /// To create a `HipOsStr` from a `'static` string slice `const`-ly, see
+    /// [`HipOsStr::from_static`].
+    ///
+    /// # Representation
+    ///
+    /// The created `HipOsStr` is _borrowed_.
     ///
     /// # Examples
     ///
@@ -218,11 +237,12 @@ where
         self.0.is_allocated()
     }
 
-    /// Converts `self` into a static string slice if this `HipOsStr` is backed by a static borrow.
+    /// Converts `self` into a string slice with the `'borrow` lifetime if this
+    /// `HipOsStr` is backed by a borrow.
     ///
     /// # Errors
     ///
-    /// Returns `Err(self)` if this `HipOsStr` is not a static borrow.
+    /// Returns `Err(self)` if this `HipOsStr` is not borrowed.
     ///
     /// # Examples
     ///
@@ -328,7 +348,7 @@ where
     /// Converts a `HipOsStr` into a `HipByt`.
     ///
     /// It consumes the `HipOsStr` without copying the content
-    /// (if [shared][Self::is_allocated] or [static][Self::is_borrowed]).
+    /// (if [shared][Self::is_allocated] or [borrowed][Self::is_borrowed]).
     ///
     /// # Examples
     ///
@@ -414,7 +434,7 @@ where
     ///
     /// This operation may reallocate a new string if either:
     ///
-    /// - the representation is not an allocated buffer (inline array or static borrow),
+    /// - the representation is not an allocated buffer (inline array or borrow),
     /// - the underlying buffer is shared.
     ///
     /// # Examples
@@ -699,9 +719,12 @@ impl<B> HipOsStr<'static, B>
 where
     B: Backend,
 {
-    /// Creates a new `HipOsStr` from a static string slice without copying the slice.
+    /// Creates a new `HipOsStr` from a `'static` string slice without copying
+    /// the slice.
+    ///
+    /// # Representation
     ///
-    /// Handy shortcut to make a `HipOsStr<'static, _>` out of a `&'static str`.
+    /// The created `HipOsStr` is _borrowed_.
     ///
     /// # Examples
     ///

src/path.rs

@@ -107,9 +107,18 @@ where
         Self(HipOsStr::new())
     }
 
-    /// Creates a new `HipPath` from a static os string slice without copying the slice.
+    /// Creates a new `HipPath` from an OS string slice without copying the
+    /// slice.
     ///
-    /// Requires only `impl AsRef<Path>`: it accepts `&str`, `&OsStr`, and `&Path` for instance.
+    /// Requires only `impl AsRef<Path>`: it accepts `&str`, `&OsStr`, and
+    /// `&Path` for instance.
+    ///
+    /// To create a `HipPath` from a `'static` string slice `const`-ly, see
+    /// [`HipPath::from_static`].
+    ///
+    /// # Representation
+    ///
+    /// The created `HipPath` is _borrowed_.
     ///
     /// # Examples
     ///
@@ -196,11 +205,12 @@ where
         self.0.is_allocated()
     }
 
-    /// Converts `self` into a static string slice if this `HipPath` is backed by a static borrow.
+    /// Converts `self` into a path slice with the `'borrow` lifetime if this
+    /// `HipPath` is backed by a borrow.
     ///
     /// # Errors
     ///
-    /// Returns `Err(self)` if this `HipPath` is not a static borrow.
+    /// Returns `Err(self)` if this `HipPath` is not borrowed.
     ///
     /// # Examples
     ///
@@ -366,7 +376,7 @@ where
     ///
     /// This operation may reallocate a new buffer if either:
     ///
-    /// - the representation is not an allocated buffer (inline array or static borrow),
+    /// - the representation is not an allocated buffer (inline array or borrow),
     /// - the underlying buffer is shared.
     ///
     /// # Examples
@@ -533,7 +543,9 @@ where
 {
     /// Creates a new `HipPath` from a static string slice without copying the slice.
     ///
-    /// Handy shortcut to make a `HipPath<'static, _>` out of a `&'static str`.
+    /// # Representation
+    ///
+    /// The created `HipPath` is _borrowed_.
     ///
     /// # Examples
     ///

src/string.rs

@@ -103,8 +103,9 @@ where
 
     /// Creates a new `HipStr` with the given capacity.
     ///
-    /// The returned `HipStr` will be able to hold at least `capacity` bytes
-    /// without reallocating or changing representation.
+    /// The final capacity depends on the representation and is not guaranteed
+    /// to be exact. However, the returned `HipStr` will be able to hold at
+    /// least `capacity` bytes without reallocating or changing representation.
     ///
     /// # Representation
     ///
@@ -134,11 +135,16 @@ where
     }
 
     /// Creates a new `HipStr` from a string slice.
+    ///
     /// No heap allocation is performed.
-    /// **The string is not copied.**
+    /// **The string slice is borrowed and not copied.**
     ///
     /// See also [`HipStr::from_static`] to ensure the borrow is `'static`.
     ///
+    /// # Representation
+    ///
+    /// The created `HipStr` is _borrowed_.
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -177,7 +183,7 @@ where
         self.0.is_inline()
     }
 
-    /// Returns `true` if this `HipStr` is a static string borrow, `false` otherwise.
+    /// Returns `true` if this `HipStr` is a string borrow, `false` otherwise.
     ///
     /// # Examples
     ///
@@ -223,11 +229,12 @@ where
         self.0.is_allocated()
     }
 
-    /// Converts `self` into a static string slice if this `HipStr` is backed by a static borrow.
+    /// Converts `self` into a string slice with the `'borrow` lifetime if this
+    /// `HipStr` is backed by a borrow.
     ///
     /// # Errors
     ///
-    /// Returns `Err(self)` if this `HipStr` is not a static borrow.
+    /// Returns `Err(self)` if this `HipStr` is not a borrow.
     ///
     /// # Examples
     ///
@@ -1738,10 +1745,14 @@ impl<B> HipStr<'static, B>
 where
     B: Backend,
 {
-    /// Creates a new `HipStr` from a static string slice without copying the slice.
+    /// Creates a new `HipStr` from a `'static` string slice without copying the slice.
     ///
     /// Handy shortcut to make a `HipStr<'static, _>` out of a `&'static str`.
     ///
+    /// # Representation
+    ///
+    /// The created `HipStr` is _borrowed_.
+    ///
     /// # Examples
     ///
     /// Basic usage: