docs: Improve documentation comments and add usage examples

Author: fxdmhtt

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "stack-cstr"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2024"
 authors = ["Junkang Yuan <[email protected]>"]
 description = "High-performance stack-to-heap C string creation for Rust with FFI support"

Cargo.toml

@@ -2,19 +2,60 @@ use std::ffi::{CStr, CString, c_char};
 
 use crate::CStrLike;
 
+/// A heap-allocated C-compatible string wrapper.
+///
+/// `CStrHeap` owns a [`CString`] internally, and implements the
+/// [`CStrLike`] trait to provide a uniform interface with
+/// stack-allocated alternatives (e.g. `CStrStack`).
+///
+/// This is used as a fallback when the string cannot fit into
+/// a fixed-size stack buffer.
 pub struct CStrHeap {
     cstr: CString,
 }
 
 impl CStrHeap {
+    /// Creates a new `CStrHeap` from a given [`CString`].
+    ///
+    /// # Arguments
+    ///
+    /// * `s` - A [`CString`] instance to be wrapped.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::CString;
+    /// use stack_cstr::CStrHeap;
+    ///
+    /// let cstr = CString::new("hello").unwrap();
+    /// let heap = CStrHeap::new(cstr);
+    /// assert_eq!(unsafe { std::ffi::CStr::from_ptr(heap.as_ptr()) }.to_str().unwrap(), "hello");
+    /// ```
     pub fn new(s: CString) -> Self {
         Self { cstr: s }
     }
 
+    /// Returns a raw pointer to the underlying C string.
+    ///
+    /// The pointer is guaranteed to be valid as long as the `CStrHeap`
+    /// instance is alive. The string is null-terminated.
     pub fn as_ptr(&self) -> *const c_char {
         self.cstr.as_ptr()
     }
 
+    /// Returns a reference to the underlying [`CStr`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::ffi::CString;
+    /// use stack_cstr::CStrHeap;
+    ///
+    /// let cstr = CString::new("hello").unwrap();
+    /// let heap = CStrHeap::new(cstr);
+    /// let slice = heap.as_cstr();
+    /// assert_eq!(slice.to_str().unwrap(), "hello");
+    /// ```
     pub fn as_cstr(&self) -> &CStr {
         self.cstr.as_c_str()
     }

src/cstr_heap.rs

@@ -1,6 +1,44 @@
 use std::ffi::{CStr, c_char};
 
+/// A common interface for C-compatible string types used in this crate.
+///
+/// `CStrLike` abstracts over different string storage strategies
+/// (e.g. stack-allocated and heap-allocated C strings) so they can
+/// be used interchangeably.
+///
+/// Types that implement this trait guarantee:
+/// - The returned pointer from [`as_ptr`] is a valid, null-terminated
+///   C string for as long as the implementor is alive.
+/// - The returned [`CStr`] reference from [`as_cstr`] is always valid.
+///
+/// This trait is mainly intended to unify [`CStrHeap`] (heap-allocated)
+/// and `CStrStack<N>` (stack-allocated with a fixed buffer).
+///
+/// # Examples
+///
+/// ```
+/// use std::ffi::{CString, CStr};
+/// use stack_cstr::{CStrHeap, CStrLike};
+///
+/// let cstr = CString::new("hello").unwrap();
+/// let heap = CStrHeap::new(cstr);
+///
+/// // Use the trait methods
+/// let ptr = heap.as_ptr();
+/// let slice: &CStr = heap.as_cstr();
+///
+/// assert_eq!(slice.to_str().unwrap(), "hello");
+/// unsafe {
+///     assert_eq!(CStr::from_ptr(ptr).to_str().unwrap(), "hello");
+/// }
+/// ```
 pub trait CStrLike {
+    /// Returns a raw pointer to the null-terminated C string.
+    ///
+    /// The pointer is valid as long as `self` is alive.  
+    /// This is mainly intended for FFI calls.
     fn as_ptr(&self) -> *const c_char;
+
+    /// Returns a reference to the underlying [`CStr`].
     fn as_cstr(&self) -> &CStr;
 }

src/cstr_like.rs

@@ -4,12 +4,51 @@ use arrayvec::ArrayString;
 
 use crate::CStrLike;
 
+/// A stack-allocated C string with a fixed buffer size.
+///
+/// `CStrStack<N>` stores a formatted string directly on the stack
+/// with a buffer of `N` bytes, avoiding heap allocation.  
+/// It always appends a trailing `\0` (null terminator) so it can be safely
+/// passed to C FFI functions.
+///
+/// If the formatted string (plus the null terminator) does not fit
+/// into the buffer, [`new`] will return an error.
+///
+/// # Examples
+///
+/// ```
+/// use std::ffi::CStr;
+/// use stack_cstr::{CStrStack, CStrLike};
+///
+/// // Create a stack-allocated C string with capacity for 32 bytes
+/// let s = CStrStack::<32>::new(format_args!("Hello {}", 123)).unwrap();
+///
+/// let cstr: &CStr = s.as_cstr();
+/// assert_eq!(cstr.to_str().unwrap(), "Hello 123");
+///
+/// unsafe {
+///     // FFI-safe pointer
+///     assert_eq!(CStr::from_ptr(s.as_ptr()).to_str().unwrap(), "Hello 123");
+/// }
+/// ```
+///
+/// # Errors
+///
+/// Returns `Err("stack buffer overflow")` if the formatted string is too
+/// long to fit in the buffer.
+///
+/// Returns `Err("format failed")` if formatting the string fails
+/// (rare case, usually only if the formatter writes an error).
 pub struct CStrStack<const N: usize> {
     buf: [u8; N],
     len: usize,
 }
 
 impl<const N: usize> CStrStack<N> {
+    /// Creates a new stack-allocated C string using a `format_args!` expression.
+    ///
+    /// The string is written into an internal buffer of size `N`.
+    /// If the string does not fit, returns an error.
     pub fn new(fmt: std::fmt::Arguments) -> Result<CStrStack<N>, &'static str> {
         let mut buf: ArrayString<N> = ArrayString::new();
         std::fmt::write(&mut buf, fmt).map_err(|_| "format failed")?;
@@ -29,10 +68,20 @@ impl<const N: usize> CStrStack<N> {
         })
     }
 
+    /// Returns a raw pointer to the null-terminated C string.
+    ///
+    /// This pointer is valid for as long as `self` is alive.
+    /// Suitable for passing to FFI.
     pub fn as_ptr(&self) -> *const c_char {
         self.buf.as_ptr() as *const c_char
     }
 
+    /// Returns a reference to the underlying [`CStr`].
+    ///
+    /// # Safety
+    ///
+    /// The buffer is guaranteed to be null-terminated by construction,
+    /// so this is always safe.
     pub fn as_cstr(&self) -> &CStr {
         unsafe { CStr::from_bytes_with_nul_unchecked(&self.buf[..self.len + 1]) }
     }

src/cstr_stack.rs

@@ -1,3 +1,104 @@
+//! # stack_cstr
+//!
+//! `stack_cstr` provides ergonomic and efficient ways to create
+//! [`CStr`](std::ffi::CStr) values for FFI interoperability.
+//!
+//! The crate offers both **stack-based** and **heap-based** strategies
+//! for storing C-compatible strings. Its goal is to minimize heap
+//! allocations for short-lived or short strings while providing
+//! automatic fallback to the heap when needed.
+//!
+//! ## Motivation
+//!
+//! When interacting with C APIs, strings must be passed as
+//! null-terminated `*const c_char`. The standard way in Rust
+//! is to use [`CString`], which always allocates on the heap.
+//!
+//! However, in performance-sensitive or embedded environments,
+//! frequent heap allocations are undesirable. `stack_cstr` allows
+//! you to create `CStr` objects backed by **fixed-size stack buffers**,
+//! avoiding heap allocations for common short strings.
+//!
+//! ## Core Components
+//!
+//! - [`CStrLike`](crate::CStrLike): A trait for types that can expose
+//!   a `*const c_char` and a `&CStr`.
+//! - [`CStrStack`](crate::CStrStack): A stack-allocated C string with
+//!   a user-defined capacity.
+//! - [`CStrHeap`](crate::CStrHeap): A heap-allocated C string wrapper
+//!   around [`CString`].
+//! - [`cstr!`](crate::cstr): A macro that automatically chooses between
+//!   stack or heap storage depending on the string length.
+//!
+//! ## Example: Using the `cstr!` Macro
+//!
+//! ```
+//! use std::ffi::CStr;
+//! use stack_cstr::{cstr, CStrLike};
+//!
+//! // Default stack sizes are [32, 128]
+//! let s = cstr!("Hello {}", 42);
+//! assert_eq!(s.as_cstr().to_str().unwrap(), "Hello 42");
+//!
+//! // Explicitly set candidate stack buffer sizes
+//! let s = cstr!([16, 64], "Pi = {:.2}", 3.14159);
+//! assert_eq!(s.as_cstr().to_str().unwrap(), "Pi = 3.14");
+//!
+//! unsafe {
+//!     // Pass to FFI as *const c_char
+//!     let ptr = s.as_ptr();
+//!     assert_eq!(CStr::from_ptr(ptr).to_str().unwrap(), "Pi = 3.14");
+//! }
+//! ```
+//!
+//! ## Example: Manual Use of `CStrStack`
+//!
+//! ```
+//! use stack_cstr::CStrStack;
+//!
+//! // Create a stack-allocated C string with capacity 32
+//! let s = CStrStack::<32>::new(format_args!("ABC {}!", 123)).unwrap();
+//! assert_eq!(s.as_cstr().to_str().unwrap(), "ABC 123!");
+//! ```
+//!
+//! ## Example: Manual Use of `CStrHeap`
+//!
+//! ```
+//! use std::ffi::CString;
+//! use stack_cstr::CStrHeap;
+//!
+//! let heap_str = CStrHeap::new(CString::new("Hello from heap").unwrap());
+//! assert_eq!(heap_str.as_cstr().to_str().unwrap(), "Hello from heap");
+//! ```
+//!
+//! ## Design Notes
+//!
+//! - `CStrStack` checks buffer boundaries at construction time and
+//!   guarantees proper null termination.
+//! - `cstr!` hides the complexity by trying multiple stack sizes and
+//!   falling back to heap when necessary.
+//! - Returned values from `cstr!` are `Box<dyn CStrLike>` for uniformity,
+//!   even when stack-backed. This introduces a single heap allocation
+//!   for type erasure, which is usually negligible compared to string allocation.
+//!
+//! ## Use Cases
+//!
+//! - Embedding short strings in FFI calls without heap allocation.
+//! - Performance-sensitive applications where allocation patterns matter.
+//! - Embedded systems where heap memory is constrained.
+//!
+//! ## Limitations
+//!
+//! - `CStrStack` requires a compile-time constant buffer size.
+//! - Even stack-backed strings returned from `cstr!` are wrapped in a `Box`
+//!   to allow dynamic dispatch.
+//!
+//! ## See Also
+//!
+//! - [`CString`](std::ffi::CString) for heap-allocated C strings
+//! - [`CStr`](std::ffi::CStr) for borrowed C strings
+//! - [`arrayvec`](https://docs.rs/arrayvec) used internally for formatting
+
 pub mod cstr_heap;
 pub mod cstr_like;
 pub mod cstr_stack;

src/lib.rs

@@ -1,3 +1,65 @@
+/// A macro to create a C-compatible string (`&CStr`) with stack allocation fallback.
+///
+/// The `cstr!` macro tries to construct a [`CStrStack`] with one of the given
+/// buffer sizes. If none of the stack sizes is large enough, it falls back to
+/// allocating a [`CString`] on the heap.
+///
+/// This makes it ergonomic to create FFI-safe strings with minimal overhead.
+/// Common short strings will use stack buffers, while longer strings
+/// automatically use heap allocation.
+///
+/// # Syntax
+///
+/// ```ignore
+/// cstr!([sizes...], "format string", args...)
+/// cstr!("format string", args...)   // uses default sizes [32, 128]
+/// ```
+///
+/// - `sizes...`: A list of candidate stack buffer sizes.  
+///   The macro tries each size in order until one succeeds.  
+///   If all fail, a heap allocation is used.  
+/// - `"format string", args...`: A format string and its arguments,
+///   just like in `format!`.
+///
+/// # Returns
+///
+/// A `Box<dyn CStrLike>`, which can be used to obtain:
+/// - a raw pointer (`*const c_char`) via [`CStrLike::as_ptr`]
+/// - a reference to the [`CStr`] via [`CStrLike::as_cstr`]
+///
+/// # Examples
+///
+/// ```
+/// use std::ffi::CStr;
+/// use stack_cstr::{cstr, CStrLike};
+///
+/// // Use default sizes [32, 128]
+/// let s = cstr!("Hello {}", 42);
+/// assert_eq!(s.as_cstr().to_str().unwrap(), "Hello 42");
+///
+/// // Explicit stack sizes
+/// let s = cstr!([16, 64], "Pi = {:.2}", 3.14159);
+/// assert_eq!(s.as_cstr().to_str().unwrap(), "Pi = 3.14");
+///
+/// unsafe {
+///     // Pass to FFI as *const c_char
+///     assert_eq!(CStr::from_ptr(s.as_ptr()).to_str().unwrap(), "Pi = 3.14");
+/// }
+/// ```
+///
+/// # Notes
+///
+/// - If the formatted string fits in one of the provided stack buffers,
+///   no heap allocation is performed.  
+/// - If the string is too long for all stack buffers, it is allocated on the heap.
+/// - The returned type is `Box<dyn CStrLike>`, which is heap-allocated for
+///   type erasure even when the string is stack-based. This indirection is
+///   usually negligible.
+///
+/// # See also
+///
+/// - [`CStrStack`] for stack-only storage
+/// - [`CStrHeap`] for explicit heap allocation
 #[macro_export]
 macro_rules! cstr {
     ([$($size:expr),*], $($args:tt)*) => {{