Various documentation improvements

audio-core/src/buf.rs

@@ -159,7 +159,7 @@ pub trait Buf {
     /// ```
     fn iter(&self) -> Self::Iter<'_>;
 
-    /// Construct a new buffer where `n` frames are skipped.
+    /// Construct a wrapper around this buffer that skips the first `n` frames.
     ///
     /// # Examples
     ///
@@ -195,7 +195,7 @@ pub trait Buf {
         Skip::new(self, n)
     }
 
-    /// Construct a new buffer where `n` frames are skipped.
+    /// Construct a wrapper around this buffer that skips the last `n` frames.
     ///
     /// # Examples
     ///
@@ -239,7 +239,7 @@ pub trait Buf {
         Tail::new(self, n)
     }
 
-    /// Limit the channel buffer to `limit` number of frames.
+    /// Construct a wrapper around this buffer which stops after `limit` frames.
     ///
     /// # Examples
     ///

audio-core/src/channel.rs

@@ -1,10 +1,9 @@
 //! A channel buffer as created through [Buf::get][crate::Buf::get] or
 //! [BufMut::get_mut][crate::BufMut::get_mut].
 
-/// The buffer of a single channel.
+/// One channel of audio samples, usually one of several channels in a multichannel buffer
 ///
-/// This doesn't provide direct access to the underlying buffer, but rather
-/// allows us to copy data usinga  number of utility functions.
+/// This trait provides read-only access.
 ///
 /// See [Buf::get][crate::Buf::get].
 pub trait Channel {

audio-core/src/channel_mut.rs

@@ -1,9 +1,8 @@
 use crate::Channel;
 
-/// The mutable buffer of a single channel.
+/// One channel of audio samples, usually one of several channels in a multichannel buffer
 ///
-/// This doesn't provide direct access to the underlying buffer, but rather
-/// allows us to copy data usinga  number of utility functions.
+/// This trait provides read and write access.
 ///
 /// See [BufMut::get_mut][crate::BufMut::get_mut].
 pub trait ChannelMut: Channel {

audio/src/buf/dynamic.rs

@@ -16,7 +16,7 @@ pub use self::iter::{Iter, IterMut};
 /// A dynamically sized, multi-channel audio buffer.
 ///
 /// An audio buffer can only be resized if it contains a type which is
-/// sample-apt For more information of what this means, see [Sample].
+/// sample-apt. For more information of what this means, see [Sample].
 ///
 /// This kind of buffer stores each channel in its own heap-allocated slice of
 /// memory, meaning they can be manipulated more cheaply independently of each
@@ -316,7 +316,7 @@ impl<T> Dynamic<T> {
 
                 for n in 0..self.channels_cap {
                     // Safety: We control the known sizes, so we can guarantee
-                    // that the slice is allocated and sized tio exactly `from`.
+                    // that the slice is allocated and sized to exactly `from`.
                     unsafe {
                         self.data
                             .get_unchecked_mut(n)

audio/src/buf/interleaved/buf.rs

@@ -14,7 +14,7 @@ use crate::frame::{InterleavedFrame, InterleavedFramesIter, RawInterleaved};
 /// A dynamically sized, multi-channel interleaved audio buffer.
 ///
 /// An audio buffer can only be resized if it contains a type which is
-/// sample-apt For more information of what this means, see [Sample].
+/// sample-apt. For more information of what this means, see [Sample].
 ///
 /// An *interleaved* audio buffer stores all audio data interleaved in memory,
 /// one sample from each channel in sequence until we're out of samples. This

audio/src/buf/sequential/buf.rs

@@ -16,7 +16,7 @@ use crate::frame::{RawSequential, SequentialFrame, SequentialFramesIter};
 /// one channel after another.
 ///
 /// An audio buffer can only be resized if it contains a type which is
-/// sample-apt For more information of what this means, see [Sample].
+/// sample-apt. For more information of what this means, see [Sample].
 ///
 /// Resizing the buffer might therefore cause a fair bit of copying, and for the
 /// worst cases, this might result in having to copy a memory region

audio/src/channel.rs

@@ -1,4 +1,4 @@
-//! Channel buffers.
+//! Structs for accessing a single channel of audio within a multichannel buffer
 //!
 //! * [LinearChannelMut] and [LinearChannel] wraps a mutable and immutable *linear* channel
 //!   buffer respectively.

audio/src/channel/interleaved.rs

@@ -34,12 +34,9 @@ slice_comparisons!({'a, T}, InterleavedChannelMut<'a, T>, [T]);
 slice_comparisons!({'a, T}, InterleavedChannelMut<'a, T>, &[T]);
 slice_comparisons!(#[cfg(feature = "std")] {'a, T}, InterleavedChannelMut<'a, T>, Vec<T>);
 
-/// The buffer of a single interleaved channel.
-///
-/// This doesn't provide direct access to the underlying buffer, but rather
-/// allows us to copy data usinga  number of utility functions.
-///
-/// See [Buf::get][crate::Buf::get].
+/// Read-only access to a single channel of audio within an interleaved, multichannel audio buffer.
+/// This struct does not own the audio data; it provides an API for accessing data owned by something else.
+/// See also [crate::buf::Interleaved].
 pub struct InterleavedChannel<'a, T> {
     /// The base pointer of the buffer.
     ptr: ptr::NonNull<T>,
@@ -95,12 +92,9 @@ impl<'a, T> InterleavedChannel<'a, T> {
     }
 }
 
-/// The buffer of a single interleaved channel.
-///
-/// This doesn't provide direct access to the underlying buffer, but rather
-/// allows us to copy data usinga  number of utility functions.
-///
-/// See [BufMut::get_mut][crate::BufMut::get_mut].
+/// Read-write access to a single channel of audio within an interleaved, multichannel audio buffer.
+/// This struct does not own the audio data; it provides an API for accessing data owned by something else.
+/// See also [crate::buf::Interleaved].
 pub struct InterleavedChannelMut<'a, T> {
     /// The base pointer of the buffer.
     ptr: ptr::NonNull<T>,

audio/src/channel/linear.rs

@@ -24,12 +24,9 @@ slice_comparisons!({'a, T}, LinearChannelMut<'a, T>, [T]);
 slice_comparisons!({'a, T}, LinearChannelMut<'a, T>, &[T]);
 slice_comparisons!(#[cfg(feature = "std")] {'a, T}, LinearChannelMut<'a, T>, Vec<T>);
 
-/// The buffer of a single linear channel.
-///
-/// This doesn't provide direct access to the underlying buffer, but rather
-/// allows us to copy data usinga  number of utility functions.
-///
-/// See [Buf::get][crate::Buf::get].
+/// Read-only access to a single channel of audio within a linear, multichannel audio buffer.
+/// This struct does not own the audio data; it provides an API for accessing data owned by something else.
+/// See also [crate::buf::Sequential].
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(transparent)]
 pub struct LinearChannel<'a, T> {
@@ -163,12 +160,9 @@ where
     }
 }
 
-/// The buffer of a single linear channel.
-///
-/// This doesn't provide direct access to the underlying buffer, but rather
-/// allows us to copy data usinga  number of utility functions.
-///
-/// See [Buf::get][crate::Buf::get].
+/// Read-write access to a single channel of audio within a linear, multichannel audio buffer.
+/// This struct does not own the audio data; it provides an API for accessing data owned by something else.
+/// See also [crate::buf::Sequential].
 #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct LinearChannelMut<'a, T> {
     /// The underlying channel buffer.

audio/src/lib.rs

@@ -8,41 +8,41 @@
 //! This is made up of several parts, each can be used independently of each
 //! other:
 //!
-//! * [audio-core] - The core crate, which defines traits that allows for safely
-//!   interacting with audio buffers.
+//! * [audio-core] - The core crate, which defines traits that allows for
+//!   interacting with audio buffers independent of their layout in memory.
 //! * [audio] - This crate, which provides a collection of high-quality audio
 //!   buffers which implements the traits provided in [audio-core].
 //! * [audio-device] - A crate for interacting with audio devices in idiomatic
 //!   Rust.
 //! * [audio-generator] - A crate for generating audio.
 //!
 //! Audio buffers provided by this crate have zero or more channels that can be
-//! iterated over. A channel is simply a sequence of samples. This can be stored
-//! using different topologies as appropriate which will be detailed in the next
-//! section.
+//! iterated over. A channel is simply a sequence of samples. The samples within
+//! each channel at one moment in time are a frame. A buffer can store channels
+//! in various ways in memory, as detailed in the next section.
 //!
 //! <br>
 //!
-//! ## Formats and topologies
+//! ## Buffers
 //!
-//! The following are the three canonical audio formats which are supported by
-//! this crate. All of the examples represent how the two channels `[1, 2, 3,
-//! 4]` and `[5, 6, 7, 8]` are stored:
+//! This crate provides several structs for storing buffers of multichannel audio.
+//! The examples represent how the two channels `[1, 2, 3, 4]` and `[5, 6, 7, 8]`
+//! are stored in memory:
 //!
-//! * [dynamic][Dynamic] - where each channel is stored in its own
-//!   heap-allocated buffer. Each channel is stored sequentially in their own
-//!   allocations. So `[1, 2, 3, 4]` and `[5, 6, 7, 8]`. Having separate
-//!   allocations for each channel can be useful if the topologies of the
-//!   buffers keep frequently changing since changing the number of channels
-//!   does not require any re-allocation of existing ones.
-//! * [interleaved][Interleaved] - where each channel is interleaved into one
-//!   buffer. So `[1, 5, 2, 6, 3, 7, 4, 8]`.
-//! * [sequential][Sequential] - where each channel is stored in a linear
-//!   buffer, one after another. So `[1, 2, 3, 4, 5, 6, 7, 8]`.
+//! * [Dynamic]: each channel is stored in its own heap allocation.
+//!   So `[1, 2, 3, 4]` and `[5, 6, 7, 8]`. This may be more performant when
+//!   resizing freqently. Generally prefer one of the other buffer types for
+//!   better CPU cache locality.
+//! * [Interleaved]: samples of each channel are interleaved
+//!   in one heap allocation. So `[1, 5, 2, 6, 3, 7, 4, 8]`.
+//! * [Sequential]: each channel is stored one after the other
+//!   in one heap allocation. So `[1, 2, 3, 4, 5, 6, 7, 8]`.
 //!
 //! These all implement the [Buf] and [BufMut] traits, allowing library authors
 //! to abstract over any one specific format. The exact channel and frame count
-//! of a buffer is known as its *topology*.
+//! of a buffer is known as its *topology*. The following example allocates
+//! buffers with 4 frames and 2 channels. The buffers are arranged in memory
+//! differently, but data is copied into them using the same API.
 //!
 //! ```rust
 //! use audio::{BufMut, ChannelMut};
@@ -57,7 +57,9 @@
 //! ```
 //!
 //! We also support [wrapping][wrap] external buffers so that they can
-//! interoperate like other audio buffers.
+//! interoperate like other audio buffers. Library authors using the [Buf]/[BufMut]
+//! traits as generic inputs to functions should re-export the [wrap] module so
+//! users of the library are not required to use this crate's buffer structs.
 //!
 //! <br>
 //!

audio/src/wrap.rs

@@ -1,5 +1,8 @@
-//! Wrap an external type to implement [Buf][crate::Buf] and
-//! [BufMut][crate::BufMut].
+//! This module provides wrappers to pass audio data from crates which
+//! use different buffer formats into functions that take [Buf][crate::Buf]
+//! or [BufMut][crate::BufMut] without needing to copy data into an intermediate
+//! buffer. They may also be useful for incrementally introducing this crate
+//! into a codebase that uses a different buffer format.
 
 use crate::slice::Slice;
 
@@ -14,7 +17,7 @@ mod dynamic;
 #[cfg(feature = "std")]
 pub use self::dynamic::Dynamic;
 
-/// Wrap a `value` as an interleaved buffer with the given number of channels.
+/// Wrap a slice as an interleaved buffer with the given number of channels.
 ///
 /// Certain interleaved buffers can be used conveniently as implementors of
 /// [ReadBuf][crate::ReadBuf] and [WriteBuf][crate::WriteBuf], due to the
@@ -69,7 +72,7 @@ where
     Interleaved::new(value, channels)
 }
 
-/// Wrap a `value` as a sequential buffer with the given number of frames. The
+/// Wrap a slice as a sequential buffer with the given number of frames. The
 /// length of the buffer determines the number of channels it has.
 ///
 /// Unlike [interleaved][interleaved()], wrapped sequential buffers cannot be
@@ -85,8 +88,8 @@ where
     Sequential::new(value, channels)
 }
 
-/// Wrap a dynamically sized buffer where each channel must not necessarily be
-/// equally sized.
+/// Wrap a [Vec] of Vecs or slice of Vecs where each inner Vec is a channel.
+/// The channels do not need to be equally sized.
 ///
 /// This should only be used for external types which you have no control over
 /// or if you legitimately need a buffer which doesn't have uniformly sized
@@ -98,7 +101,7 @@ where
 /// ```
 /// use audio::Buf;
 ///
-/// let buf = [vec![1, 2, 3, 4], vec![5, 6]];
+/// let buf = vec![vec![1, 2, 3, 4], vec![5, 6]];
 /// let buf = audio::wrap::dynamic(&buf[..]);
 /// assert_eq!(buf.channels(), 2);
 /// assert_eq!(buf.frames_hint(), Some(4));