docs: additional documentation (#27)

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

README.md

@@ -65,6 +65,37 @@ some cases where you might be better off considering other options:
 - **You want an unbounded channel**. I'm not going to write an unbounded
   channel. Unbounded channels are evil.
 
+## Usage
+
+To get started using `thingbuf`, add the following to your `Cargo.toml`:
+
+```toml
+[dependencies]
+thingbuf = "0.1"
+```
+
+By default, `thingbuf` depends on the Rust standard library, in order to
+implement APIs such as synchronous (blocking) channels. In `#![no_std]`
+projects, the `std` feature flag must be disabled:
+
+```toml
+[dependencies]
+thingbuf = { version = "0.1", default-features = false }
+```
+
+With the `std` feature disabled, `thingbuf` will depend only on `libcore`. This
+means that APIs that require dynamic memory allocation will not be enabled.
+Statically allocated [channels][static-mpsc] and [queues][static-queue] are
+available for code without a memory allocator.
+
+However, if a memory allocator _is_ available, `#![no_std]` code can also enable
+the `alloc` feature flag to depend on `liballoc`:
+
+```toml
+[dependencies]
+thingbuf = { version = "0.1", default-features = false, features = ["alloc"] }
+```
+
 ## FAQs
 
 - **Q: Why did you make this?**

src/lib.rs

@@ -1,6 +1,6 @@
 #![cfg_attr(docsrs, doc = include_str!("../README.md"))]
 #![cfg_attr(not(feature = "std"), no_std)]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 use core::{cmp, fmt, mem::MaybeUninit, ops};
 
 #[macro_use]
@@ -39,12 +39,15 @@ use crate::{
     util::{Backoff, CachePadded},
 };
 
+/// A reference to an entry in a [`ThingBuf`].
 pub struct Ref<'slot, T> {
     ptr: MutPtr<MaybeUninit<T>>,
     slot: &'slot Slot<T>,
     new_state: usize,
 }
 
+/// Error returned when sending a message failed because a channel is at capacity.
+
 pub struct Full<T = ()>(T);
 
 /// State variables for the atomic ring buffer algorithm.

src/thingbuf.rs

@@ -6,6 +6,7 @@ use core::{fmt, ptr};
 #[cfg(all(loom, test))]
 mod tests;
 
+/// A fixed-size, lock-free multi-producer multi-consumer queue.
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub struct ThingBuf<T> {
     pub(crate) core: Core,
@@ -15,6 +16,7 @@ pub struct ThingBuf<T> {
 // === impl ThingBuf ===
 
 impl<T: Default> ThingBuf<T> {
+    /// Return a new `ThingBuf` with space for `capacity` entries.
     pub fn new(capacity: usize) -> Self {
         assert!(capacity > 0);
         Self {
@@ -23,6 +25,11 @@ impl<T: Default> ThingBuf<T> {
         }
     }
 
+    /// Reserve a slot to push an entry into the queue, returning a [`Ref`] that
+    /// can be used to write to that slot.
+    ///
+    /// This can be used to reuse allocations for queue entries in place,
+    /// by clearing previous data prior to writing.
     pub fn push_ref(&self) -> Result<Ref<'_, T>, Full> {
         self.core.push_ref(&*self.slots).map_err(|e| match e {
             crate::mpsc::TrySendError::Full(()) => Full(()),
@@ -35,6 +42,8 @@ impl<T: Default> ThingBuf<T> {
         self.push_ref().map(|mut r| r.with_mut(f))
     }
 
+    /// Dequeue the first element in the queue, returning a [`Ref`] that can be
+    /// used to read from (or mutate) the element.
     pub fn pop_ref(&self) -> Option<Ref<'_, T>> {
         self.core.pop_ref(&*self.slots).ok()
     }
@@ -46,16 +55,81 @@ impl<T: Default> ThingBuf<T> {
 }
 
 impl<T> ThingBuf<T> {
+    /// Returns the total capacity of the `ThingBuf`. This includes both
+    /// occupied and unoccupied entries.
+    ///
+    /// The number of _unoccupied_ entries can be determined by subtracing the
+    /// value returned by [`len`] from the value returned by `capacity`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use thingbuf::ThingBuf;
+    ///
+    /// let q = ThingBuf::<usize>::new(100);
+    /// assert_eq!(q.capacity(), 100);
+    /// ```
+    ///
+    /// Even after pushing several messages to the queue, the capacity remains
+    /// the same:
+    /// ```
+    /// # use thingbuf::ThingBuf;
+    ///
+    /// let q = ThingBuf::<usize>::new(100);
+    ///
+    /// *q.push_ref().unwrap() = 1;
+    /// *q.push_ref().unwrap() = 2;
+    /// *q.push_ref().unwrap() = 3;
+    ///
+    /// assert_eq!(q.capacity(), 100);
+    /// ```
     #[inline]
     pub fn capacity(&self) -> usize {
         self.slots.len()
     }
 
+    /// Returns the number of messages in the queue
+    ///
+    /// The number of _unoccupied_ entries can be determined by subtracing the
+    /// value returned by [`len`] from the value returned by `capacity`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use thingbuf::ThingBuf;
+    ///
+    /// let q = ThingBuf::<usize>::new(100);
+    /// assert_eq!(q.len(), 0);
+    ///
+    /// *q.push_ref().unwrap() = 1;
+    /// *q.push_ref().unwrap() = 2;
+    /// *q.push_ref().unwrap() = 3;
+    /// assert_eq!(q.len(), 3);
+    ///
+    /// let _ = q.pop_ref();
+    /// assert_eq!(q.len(), 2);
+    /// ```
     #[inline]
     pub fn len(&self) -> usize {
         self.core.len()
     }
 
+    /// Returns `true` if there are currently no entries in this `ThingBuf`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use thingbuf::ThingBuf;
+    ///
+    /// let q = ThingBuf::<usize>::new(100);
+    /// assert!(q.is_empty());
+    ///
+    /// *q.push_ref().unwrap() = 1;
+    /// assert!(!q.is_empty());
+    ///
+    /// let _ = q.pop_ref();
+    /// assert!(q.is_empty());
+    /// ```
     #[inline]
     pub fn is_empty(&self) -> bool {
         self.len() == 0