Add some items documentation to ringbuf, slightly reorganize modules

async/src/rb.rs

@@ -6,7 +6,7 @@ use futures::task::AtomicWaker;
 #[cfg(feature = "alloc")]
 use ringbuf::traits::Split;
 use ringbuf::{
-    rb::traits::RbRef,
+    rb::RbRef,
     storage::Storage,
     traits::{Consumer, Observer, Producer, RingBuffer, SplitRef},
     SharedRb,

async/src/wrap/cons.rs

@@ -11,7 +11,7 @@ use ringbuf::{
         consumer::{Consumer, DelegateConsumer},
         Observer,
     },
-    wrap::traits::Wrap,
+    wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

async/src/wrap/mod.rs

@@ -4,7 +4,7 @@ mod prod;
 use crate::rb::AsyncRbRef;
 use ringbuf::{
     traits::{observer::DelegateObserver, Based},
-    wrap::{direct::Direct, traits::Wrap},
+    wrap::{direct::Direct, Wrap},
     Obs,
 };
 

async/src/wrap/prod.rs

@@ -13,7 +13,7 @@ use ringbuf::{
         producer::{DelegateProducer, Producer},
         Observer,
     },
-    wrap::traits::Wrap,
+    wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

blocking/src/rb.rs

@@ -7,7 +7,7 @@ use core::{mem::MaybeUninit, num::NonZeroUsize};
 #[cfg(feature = "alloc")]
 use ringbuf::traits::Split;
 use ringbuf::{
-    rb::traits::RbRef,
+    rb::RbRef,
     storage::Storage,
     traits::{Consumer, Observer, Producer, RingBuffer, SplitRef},
     SharedRb,

blocking/src/wrap/cons.rs

@@ -5,7 +5,7 @@ use core::time::Duration;
 use ringbuf::traits::Based;
 use ringbuf::{
     traits::{consumer::DelegateConsumer, observer::DelegateObserver, Consumer, Observer},
-    wrap::traits::Wrap,
+    wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

blocking/src/wrap/mod.rs

@@ -5,7 +5,7 @@ use crate::rb::BlockingRbRef;
 use core::time::Duration;
 use ringbuf::{
     traits::Based,
-    wrap::{caching::Caching, traits::Wrap},
+    wrap::{caching::Caching, Wrap},
     Obs,
 };
 

blocking/src/wrap/prod.rs

@@ -5,7 +5,7 @@ use core::time::Duration;
 use ringbuf::traits::Based;
 use ringbuf::{
     traits::{observer::DelegateObserver, producer::DelegateProducer, Observer, Producer},
-    wrap::traits::Wrap,
+    wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

src/lib.rs

@@ -1,6 +1,8 @@
+//! Lock-free SPSC FIFO ring buffer with direct access to inner data.
+//!
+//! For implementation details see [`RingBuffer`](`traits::RingBuffer`) description.
 #![no_std]
 #![allow(clippy::type_complexity)]
-#![allow(clippy::missing_safety_doc)]
 #![cfg_attr(feature = "bench", feature(test))]
 
 #[cfg(feature = "alloc")]

src/rb/local.rs

@@ -34,6 +34,8 @@ impl End {
 }
 
 /// Ring buffer for single-threaded use only.
+///
+/// Slightly faster than multi-threaded version because it doesn't synchronize cache.
 pub struct LocalRb<S: Storage> {
     storage: Shared<S>,
     read: End,
@@ -46,7 +48,7 @@ impl<S: Storage> LocalRb<S> {
     /// # Safety
     ///
     /// The items in storage inside `read..write` range must be initialized, items outside this range must be uninitialized.
-    /// `read` and `write` positions must be valid (see [`RbBase`](`crate::ring_buffer::RbBase`)).
+    /// `read` and `write` positions must be valid (see implementation details).
     pub unsafe fn from_raw_parts(storage: S, read: usize, write: usize) -> Self {
         Self {
             storage: Shared::new(storage),

src/rb/mod.rs

@@ -1,8 +1,11 @@
+/// Single-threaded ring buffer implementation.
 pub mod local;
 mod macros;
+/// Multi-threaded ring buffer implementation.
 pub mod shared;
-pub mod traits;
+mod traits;
 mod utils;
 
 pub use local::LocalRb;
 pub use shared::SharedRb;
+pub use traits::*;

src/rb/shared.rs

@@ -22,8 +22,8 @@ use crossbeam_utils::CachePadded;
 
 /// Ring buffer that can be shared between threads.
 ///
-/// Note that there is no explicit requirement of `T: Send`. Instead [`Rb`] will work just fine even with `T: !Send`
-/// until you try to send its [`Prod`] or [`Cons`] to another thread.
+/// Note that there is no explicit requirement of `T: Send`. Instead ring buffer will work just fine even with `T: !Send`
+/// until you try to send its producer or consumer to another thread.
 #[cfg_attr(
     feature = "std",
     doc = r##"
@@ -58,7 +58,7 @@ impl<S: Storage> SharedRb<S> {
     /// # Safety
     ///
     /// The items in storage inside `read..write` range must be initialized, items outside this range must be uninitialized.
-    /// `read` and `write` positions must be valid (see [`RbBase`](`crate::ring_buffer::RbBase`)).
+    /// `read` and `write` positions must be valid (see implementation details).
     pub unsafe fn from_raw_parts(storage: S, read: usize, write: usize) -> Self {
         Self {
             storage: Shared::new(storage),

src/rb/traits.rs

@@ -2,8 +2,15 @@ use crate::traits::RingBuffer;
 #[cfg(feature = "alloc")]
 use alloc::{rc::Rc, sync::Arc};
 
+/// Abstract pointer to the owning ring buffer.
+///
+/// # Safety
+///
+/// Implementation must be fair (e.g. not replacing pointers between calls and so on).
 pub unsafe trait RbRef: Clone + AsRef<Self::Rb> {
+    /// Underlying ring buffer.
     type Rb: RingBuffer;
+    /// Get ring buffer reference.
     fn rb(&self) -> &Self::Rb {
         self.as_ref()
     }

src/storage.rs

@@ -6,10 +6,13 @@ use core::{cell::UnsafeCell, mem::MaybeUninit, num::NonZeroUsize, ops::Range, sl
 ///
 /// Storage items must be stored as a contiguous array.
 ///
+/// Storage is converted to internal representation before use (see [`Self::Internal`]).
+///
 /// # Safety
 ///
-/// *[`Self::len`]/[`Self::is_empty`] must always return the same value.*
+/// *[`Self::len`] must always return the same value.*
 pub unsafe trait Storage {
+    /// Stored item.
     type Item: Sized;
 
     /// Internal representation of the storage.
@@ -143,6 +146,8 @@ impl<S: Storage> Shared<S> {
     }
 }
 
+/// Static storage.
 pub type Static<T, const N: usize> = [MaybeUninit<T>; N];
+/// Heap storage.
 #[cfg(feature = "alloc")]
 pub type Heap<T> = Vec<MaybeUninit<T>>;

src/traits/consumer.rs

@@ -9,6 +9,13 @@ use std::io::{self, Write};
 
 /// Consumer part of ring buffer.
 pub trait Consumer: Observer {
+    /// Set read index.
+    ///
+    /// # Safety
+    ///
+    /// Index must go only forward, never backward. It is recommended to use [`Self::advance_read_index`] instead.
+    ///
+    /// All slots with index less than `value` must be uninitialized until write index, all slots with index equal or greater - must be initialized.
     unsafe fn set_read_index(&self, value: usize);
 
     /// Moves `read` pointer by `count` places forward.
@@ -33,7 +40,7 @@ pub trait Consumer: Observer {
     /// All items are initialized. Elements must be removed starting from the beginning of first slice.
     /// When all items are removed from the first slice then items must be removed from the beginning of the second slice.
     ///
-    /// *This method must be followed by [`Self::advance_read`] call with the number of items being removed previously as argument.*
+    /// *This method must be followed by [`Self::advance_read_index`] call with the number of items being removed previously as argument.*
     /// *No other mutating calls allowed before that.*
     fn occupied_slices(&self) -> (&[MaybeUninit<Self::Item>], &[MaybeUninit<Self::Item>]) {
         let (first, second) = unsafe { self.unsafe_slices(self.read_index(), self.write_index()) };
@@ -286,6 +293,7 @@ pub type Iter<'a, C: Consumer> = Chain<slice::Iter<'a, C::Item>, slice::Iter<'a,
 #[allow(type_alias_bounds)]
 pub type IterMut<'a, C: Consumer> = Chain<slice::IterMut<'a, C::Item>, slice::IterMut<'a, C::Item>>;
 
+/// Trait used for delegating producer methods.
 pub trait DelegateConsumer: DelegateObserver
 where
     Self::Base: Consumer,

src/traits/mod.rs

@@ -1,6 +1,10 @@
+/// Consumer functionality.
 pub mod consumer;
+/// Observer functionality.
 pub mod observer;
+/// Producer functionality.
 pub mod producer;
+/// Owning ring buffer functionality.
 pub mod ring_buffer;
 mod split;
 mod utils;

src/traits/observer.rs

@@ -1,6 +1,9 @@
 use super::{utils::modulus, Based};
 use core::{mem::MaybeUninit, num::NonZeroUsize};
 
+/// Ring buffer observer.
+///
+/// Can observe ring buffer state but cannot safely access its data.
 pub trait Observer: Sized {
     type Item: Sized;
 
@@ -9,9 +12,20 @@ pub trait Observer: Sized {
     /// It is constant during the whole ring buffer lifetime.
     fn capacity(&self) -> NonZeroUsize;
 
+    /// Index of the last item in the ring buffer.
+    ///
+    /// Index value is in range `0..(2 * capacity)`.
     fn read_index(&self) -> usize;
+    /// Index of the next empty slot in the ring buffer.
+    ///
+    /// Index value is in range `0..(2 * capacity)`.
     fn write_index(&self) -> usize;
 
+    /// Get mutable slice between `start` and `end` indices.
+    ///
+    /// # Safety
+    ///
+    /// There must not exist overlapping slices at the same time.
     unsafe fn unsafe_slices(&self, start: usize, end: usize) -> (&mut [MaybeUninit<Self::Item>], &mut [MaybeUninit<Self::Item>]);
 
     /// Whether read end is held by consumer.
@@ -52,6 +66,7 @@ pub trait Observer: Sized {
     }
 }
 
+/// Trait used for delegating observer methods.
 pub trait DelegateObserver: Based
 where
     Self::Base: Observer,

src/traits/producer.rs

@@ -14,6 +14,13 @@ use std::{
 
 /// Producer part of ring buffer.
 pub trait Producer: Observer {
+    /// Set read index.
+    ///
+    /// # Safety
+    ///
+    /// Index must go only forward, never backward. It is recommended to use [`Self::advance_write_index`] instead.
+    ///
+    /// All slots with index less than `value` must be initialized until write index, all slots with index equal or greater - must be uninitialized.
     unsafe fn set_write_index(&self, value: usize);
 
     /// Moves `write` pointer by `count` places forward.
@@ -40,8 +47,10 @@ pub trait Producer: Observer {
     /// Vacant memory is uninitialized. Initialized items must be put starting from the beginning of first slice.
     /// When first slice is fully filled then items must be put to the beginning of the second slice.
     ///
-    /// *This method must be followed by [`Self::advance_write`] call with the number of items being put previously as argument.*
+    /// *This method must be followed by [`Self::advance_write_index`] call with the number of items being put previously as argument.*
     /// *No other mutating calls allowed before that.*
+    ///
+    /// *Vacant slices must not be used to store any data because their contents aren't synchronized properly.*
     fn vacant_slices_mut(&mut self) -> (&mut [MaybeUninit<Self::Item>], &mut [MaybeUninit<Self::Item>]) {
         unsafe { self.unsafe_slices(self.write_index(), self.read_index() + self.capacity().get()) }
     }
@@ -139,6 +148,7 @@ pub trait Producer: Observer {
     }
 }
 
+/// Trait used for delegating consumer methods.
 pub trait DelegateProducer: DelegateObserver
 where
     Self::Base: Producer,

src/traits/ring_buffer.rs

@@ -4,7 +4,7 @@ use super::{
     Observer,
 };
 
-/// An abstract ring buffer.
+/// An abstract ring buffer that exclusively owns its data.
 ///
 /// # Details
 ///
@@ -17,7 +17,17 @@ use super::{
 /// without using the space for an extra element in container.
 /// And obviously we cannot store more than `capacity` items in the buffer, so `write - read` modulo `2 * capacity` is not allowed to be greater than `capacity`.
 pub trait RingBuffer: Observer + Consumer + Producer {
+    /// Tell whether read end of the ring buffer is held by consumer or not.
+    ///
+    /// # Safety
+    ///
+    /// Must not be set to `false` while consumer exists.
     unsafe fn hold_read(&self, flag: bool);
+    /// Tell whether write end of the ring buffer is held by producer or not.
+    ///
+    /// # Safety
+    ///
+    /// Must not be set to `false` while producer exists.
     unsafe fn hold_write(&self, flag: bool);
 
     /// Pushes an item to the ring buffer overwriting the latest item if the buffer is full.
@@ -57,6 +67,7 @@ pub trait RingBuffer: Observer + Consumer + Producer {
     }
 }
 
+/// Trait used for delegating owning ring buffer methods.
 pub trait DelegateRingBuffer: DelegateProducer + DelegateConsumer
 where
     Self::Base: RingBuffer,

src/traits/split.rs

@@ -1,19 +1,27 @@
 use crate::traits::{Consumer, Producer, RingBuffer};
 
+/// Split the ring buffer onto producer and consumer.
 pub trait Split: RingBuffer {
+    /// Producer type.
     type Prod: Producer;
+    /// Consumer type.
     type Cons: Consumer;
 
+    /// Perform splitting.
     fn split(self) -> (Self::Prod, Self::Cons);
 }
 
+/// Split the ring buffer by reference onto producer and consumer.
 pub trait SplitRef: RingBuffer {
+    /// Ref producer type.
     type RefProd<'a>: Producer + 'a
     where
         Self: 'a;
+    /// Ref consumer type.
     type RefCons<'a>: Consumer + 'a
     where
         Self: 'a;
 
+    /// Perform splitting by reference.
     fn split_ref(&mut self) -> (Self::RefProd<'_>, Self::RefCons<'_>);
 }

src/traits/utils.rs

@@ -1,9 +1,15 @@
 use super::Observer;
 use core::num::NonZeroUsize;
 
+/// Trait that should be implemented by ring buffer wrappers.
+///
+/// Used for automatically delegating methods.
 pub trait Based {
+    /// Type the wrapper based on.
     type Base;
+    /// Reference to base.
     fn base(&self) -> &Self::Base;
+    /// Mutable reference to base.
     fn base_mut(&mut self) -> &mut Self::Base;
 }