chore: rewrite some doc

Cargo.toml

@@ -12,6 +12,9 @@ edition = "2021"
 readme = "README.md"
 rust-version = "1.81.0"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [features]
 default = ["std"]
 std = ["serde/std", "serde_bytes/std"]
@@ -52,4 +55,4 @@ default-features = false
 features = ["alloc"]
 
 [lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage_nightly)'] }
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage_nightly)', 'cfg(docsrs)'] }

src/backend.rs

@@ -1,21 +1,15 @@
-//! Unstable allocated backend trait and the built-in implementations.
+//! Sealed backend trait and the built-in implementations.
 
-// #[cfg(not(feature = "unstable"))]
 pub mod rc;
 
-/// Use a local reference counted backend.
 pub use rc::Local;
-/// Shared (thread-safe) reference counted backend.
 #[cfg(target_has_atomic = "ptr")]
 pub use rc::ThreadSafe;
 
 /// Sealed marker trait for allocated backend.
-// #[cfg(not(feature = "unstable"))]
 pub trait Backend: rc::Count + 'static {}
 
-// #[cfg(not(feature = "unstable"))]
 impl Backend for Local {}
 
-// #[cfg(not(feature = "unstable"))]
 #[cfg(target_has_atomic = "ptr")]
 impl Backend for ThreadSafe {}

src/backend/rc.rs

@@ -12,10 +12,11 @@ pub trait Count {
     /// Creates a new counter that starts at one.
     fn one() -> Self;
 
-    /// Increments the counter and returns true iff the counter reaches `usize::MAX`.
+    /// Increments the counter and returns `true` iff the counter reaches
+    /// `usize::MAX`.
     fn incr(&self) -> bool;
 
-    /// Decrements the counter and returns true iff the counter reaches zero.
+    /// Decrements the counter and returns `true` iff the counter reaches zero.
     fn decr(&self) -> bool;
 
     /// Returns the current value of the counter.
@@ -25,7 +26,7 @@ pub trait Count {
 /// Local (thread-unsafe) reference counter.
 pub struct Local(Cell<usize>);
 
-/// Thread-safe reference counter.
+/// Atomic (thread-safe) reference counter.
 #[cfg(target_has_atomic = "ptr")]
 pub struct ThreadSafe(AtomicUsize);
 

src/bytes.rs

@@ -509,9 +509,15 @@ where
     ///
     /// This operation may reallocate a new vector if either:
     ///
-    /// - the representation is not an allocated buffer (inline array or static borrow),
+    /// - the representation is not _allocated_ (i.e. _inline_ or _borrowed_),
     /// - the underlying buffer is shared.
     ///
+    /// At the end, when the [`RefMut`] is dropped, the underlying
+    /// representation will be owned and normalized. That is, if the actual
+    /// required capacity is less than or equal to the maximal inline capacity,
+    /// the representation is _inline_; otherwise, the representation is
+    /// _allocated_.
+    ///
     /// # Examples
     ///
     /// ```rust

src/lib.rs

@@ -35,10 +35,14 @@
 //!
 //! The shared reference can be thread-safe or not, depending on the backend.
 //!
+//! Most operations keep string **normalized**, that is, if the string is not
+//! borrowed, the inline representation is preferred when possible.
+//!
 //! ## ⚠️ Warning!
 //!
-//! The used representation of the empty string is **unspecified** and may change between patch versions!
-//! It may be _borrowed_ or _inlined_ but will never be allocated.
+//! The used representation of the empty string is **unspecified** and may
+//! change between patch versions! It may be _borrowed_ or _inlined_ but will
+//! never be allocated.
 //!
 //! # Two Backends
 //!
@@ -60,18 +64,24 @@
 //! - pointer alignment requirement is strictly greater than **2**.
 //!
 //! For now, most common architectures are like that. However, `hipstr` will not
-//! work on new and future architectures relying on large tagged pointers
-//! (e.g. CHERI 128-bit pointers).
+//! work on new and future architectures relying on large tagged pointers (e.g.
+//! CHERI 128-bit pointers).
 //!
 //! # Features
 //!
-//! * `std` (default): uses `std` rather than `core` and `alloc`, and also provides more trait implementations (for comparison, conversions, and errors)
+//! * `std` (default): uses `std` rather than `core` and `alloc`, and also
+//!   provides more trait implementations (for comparison, conversions)
 //! * `serde`: provides serialization/deserialization support with `serde` crate
-//! * `unstable`: exposes internal `Backend` trait that may change at any moment
+//! * `bstr`: provides compatibility with [BurntSushi's bstr
+//!   crate](https://github.com/BurntSushi/bstr) make `HipByt` deref to
+//!   [`&bstr::BStr`](bstr::BStr) rather than [`&[u8]`]
+//! * `unstable`: do nothing, used to reveal unstable implementation details
 
 #![cfg_attr(miri, feature(strict_provenance))]
 #![cfg_attr(miri, feature(exposed_provenance))]
 #![cfg_attr(coverage_nightly, feature(coverage_attribute))]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![warn(clippy::pedantic, clippy::nursery, clippy::cargo)]
 #![warn(unsafe_op_in_unsafe_fn)]
@@ -104,16 +114,16 @@ pub type HipOsStr<'borrow> = os_string::HipOsStr<'borrow, ThreadSafe>;
 #[cfg(feature = "std")]
 pub type HipPath<'borrow> = path::HipPath<'borrow, ThreadSafe>;
 
-/// Thread-local byte sequence.
+/// Thread-local shared byte sequence.
 pub type LocalHipByt<'borrow> = bytes::HipByt<'borrow, Local>;
 
-/// Thread-local string.
+/// Thread-local shared string.
 pub type LocalHipStr<'borrow> = string::HipStr<'borrow, Local>;
 
-/// Thread-local byte sequence.
+/// Thread-local shared byte sequence.
 #[cfg(feature = "std")]
 pub type LocalHipOsStr<'borrow> = os_string::HipOsStr<'borrow, Local>;
 
-/// Thread-local byte sequence.
+/// Thread-local shared byte sequence.
 #[cfg(feature = "std")]
 pub type LocalHipPath<'borrow> = path::HipPath<'borrow, Local>;

src/string.rs

@@ -759,9 +759,15 @@ 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 _allocated_ (i.e. _inline_ or _borrowed_),
     /// - the underlying buffer is shared.
     ///
+    /// At the end, when the [`RefMut`] is dropped, the underlying
+    /// representation will be owned and normalized. That is, if the actual
+    /// required capacity is less than or equal to the maximal inline capacity,
+    /// the representation is _inline_; otherwise, the representation is
+    /// _allocated_.
+    ///
     /// # Examples
     ///
     /// ```rust