More docs! (and other fixes)

Author: prokopyl

atom/src/space.rs

@@ -1,4 +1,5 @@
 //! A collection of tools to assist reading and writing custom Atom types in Atom byte buffers (referred as **Spaces**).
+#![deny(missing_docs)]
 
 mod aligned;
 mod allocator;
@@ -15,4 +16,4 @@ pub use atom_writer::AtomWriter;
 pub use cursor::SpaceCursor;
 pub use reader::SpaceReader;
 pub use terminated::Terminated;
-pub use vec::{AlignedVec, VecSpaceCursor};
+pub use vec::{AlignedVec, AlignedVecCursor};

atom/src/space/aligned.rs

@@ -49,12 +49,20 @@ pub struct AlignedSpace<T> {
     data: [u8],
 }
 
+/// A slice of bytes that is properly aligned to contain Atoms (i.e. is 64-bit aligned).
+///
+/// See [`AlignedSpace`] for more information.
 pub type AtomSpace = AlignedSpace<AtomHeader>;
 
 impl<T: 'static> AlignedSpace<T> {
+    /// Creates a new boxed space from an already aligned, potentially uninitialized boxed slice of T.
+    ///
+    /// This method provides a lightweight conversion: it does not copy the contents nor perform any
+    /// (re)allocations.
     #[inline]
     pub fn from_boxed_uninit_slice(slice: Box<[MaybeUninit<T>]>) -> Box<Self> {
-        // Safety: casting MaybeUninit<T> to [u8] is always safe
+        // SAFETY: casting MaybeUninit<T> to [u8] is always safe.
+        // SAFETY: because this is MaybeUninit<T>, the slice is always aligned.
         unsafe { core::mem::transmute(slice) }
     }
 

atom/src/space/allocator.rs

@@ -11,7 +11,9 @@ use core::mem::{size_of, size_of_val, MaybeUninit};
 /// This structure allows simultaneous access to both the newly allocated slice, and all previously
 /// allocated bytes.
 pub struct SpaceWriterSplitAllocation<'a> {
+    /// All previously allocated bytes. This is guaranteed to be contiguous with `allocated`.
     pub previous: &'a mut [u8],
+    /// The requested newly-allocated bytes
     pub allocated: &'a mut [u8],
 }
 
@@ -21,12 +23,19 @@ pub struct SpaceWriterSplitAllocation<'a> {
 /// previous one.
 ///
 /// This trait is very bare-bones, in order to be trait-object-safe. As an user, you probably want
-/// to use the [`SpaceWriter`] trait, a child trait with many more utilities available, and with a
+/// to use the [`SpaceWriter`] trait, an extension trait with many more utilities available, and with a
 /// blanket implementation for all types that implement [`SpaceAllocator`].
 ///
 /// The term "allocate" is used very loosely here, as even a simple cursor over a mutable byte
 /// buffer (e.g. [`SpaceCursor`](crate::space::SpaceCursor)) can "allocate" bytes using this trait.
 ///
+/// "Allocations" made using this trait dot not imply actual system allocations. However, some
+/// implementations (such as [`AlignedVecCursor`](crate::space::AlignedVecCursor)) might perform a
+/// system reallocation if the requested space exceeds its internal capacity.
+///
+/// Other implementations, such as [`SpaceCursor`](crate::space::SpaceCursor), are guaranteed to
+/// never allocate, and will instead return an error when exceeding its capacity.
+///
 /// This trait is useful to abstract over many types of buffers, including ones than can track the
 /// amount of allocated bytes into an atom header (i.e. [`AtomWriter`]).
 pub trait SpaceAllocator {
@@ -79,6 +88,7 @@ pub trait SpaceAllocator {
     fn remaining_bytes(&self) -> &[u8];
 }
 
+///
 pub trait SpaceWriter: SpaceAllocator + Sized {
     /// Allocates and returns a new mutable byte buffer of the requested size, in bytes.
     ///

atom/src/space/cursor.rs

@@ -2,6 +2,12 @@ use crate::space::error::AtomWriteError;
 use crate::space::{SpaceAllocator, SpaceWriterSplitAllocation};
 
 /// A lightweight [`SpaceWriter`](crate::space::SpaceWriter) that writes into a mutable byte buffer using a cursor.
+///
+/// This cursor is backed by a simple mutable byte slice, and is therefore guaranteed to never
+/// allocate.
+///
+/// If the capacity of the underlying buffer is exceeded, an [`AtomWriteError::OutOfSpace`] error is
+/// returned.
 pub struct SpaceCursor<'a> {
     data: &'a mut [u8],
     allocated_length: usize,

atom/src/space/error.rs

@@ -1,3 +1,5 @@
+//! Errors related to the alignment, reading or writing of Atoms.
+
 use std::error::Error;
 use std::fmt::{Display, Formatter};
 use urid::{Uri, URID};
@@ -136,6 +138,7 @@ pub enum AtomWriteError {
         /// An user-friendly error message
         error_message: &'static str,
     },
+    /// An alignment error occurred when attempting to write to the underlying buffer.
     AlignmentError(AlignmentError),
 }
 
@@ -182,27 +185,43 @@ impl Display for AtomWriteError {
 
 impl Error for AtomWriteError {}
 
+/// Errors that can occur while writing atoms to a byte buffer.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 #[non_exhaustive]
 pub enum AtomReadError {
+    /// The URID of the atom being currently read does not match the requested type's URID.
     AtomUridMismatch {
+        /// The full URI of the requested type
         expected_uri: &'static Uri,
+        /// The URID of the requested type
         expected_urid: URID,
+        /// The atom's actual URID
         found_urid: URID,
     },
+    /// The URID of the atom being currently read is not actually a valid URID (e.g. zero).
     InvalidUrid {
+        /// The full URI of the requested type
         expected_uri: &'static Uri,
+        /// The URID of the requested type
         expected_urid: URID,
+        /// The value found in the Atom's URID header.
         found_urid: u32,
     },
+    /// A read operation tried to occur outside of the buffer's bounds
     ReadingOutOfBounds {
+        /// The amount of available bytes in the buffer
         available: usize,
+        /// The requested amount of bytes
         requested: usize,
     },
+    /// The read Atom value was invalid for the given Atom type.
     InvalidAtomValue {
+        /// The Atom type being read
         reading_type_uri: &'static Uri,
+        /// The Atom-specific error message
         error_message: &'static str,
     },
+    /// An alignment error curred when trying to read from the underlying buffer.
     AlignmentError(AlignmentError),
 }
 
@@ -255,9 +274,12 @@ impl Display for AtomReadError {
 
 impl Error for AtomReadError {}
 
+/// The global atom error type, that encompasses both read and write errors, for convenience.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 pub enum AtomError {
+    /// An error occurred when trying to read an atom from a buffer.
     ReadError(AtomReadError),
+    /// An error occurred when trying to write an atom into a buffer.
     WriteError(AtomWriteError),
 }
 

atom/src/space/reader.rs

@@ -21,6 +21,7 @@ fn split_space<T: 'static>(
 }
 
 impl<'a> SpaceReader<'a> {
+    /// Creates a new reader from a byte slice.
     #[inline]
     pub fn new(space: &'a [u8]) -> Self {
         SpaceReader { space }
@@ -166,6 +167,7 @@ impl<'a> SpaceReader<'a> {
         Ok(atom)
     }
 
+    /// Returns the currently remaining underlying bytes.
     #[inline]
     pub fn remaining_bytes(&self) -> &'a [u8] {
         self.space

atom/src/space/vec.rs

@@ -124,8 +124,8 @@ impl<T: Copy + 'static> AlignedVec<T> {
     /// Unlike other [`SpaceWriter`](crate::space::SpaceWriter) implementations, this cursor grows the underlying
     /// [`AlignedVec`] buffer if it runs out of space, instead of failing.
     #[inline]
-    pub fn write(&mut self) -> VecSpaceCursor<T> {
-        VecSpaceCursor {
+    pub fn write(&mut self) -> AlignedVecCursor<T> {
+        AlignedVecCursor {
             vec: self,
             allocated_length: 0,
         }
@@ -153,12 +153,12 @@ impl<T: Copy + 'static> AlignedVec<T> {
 /// [`AlignedVec`] buffer if it runs out of space, instead of failing.
 ///
 /// This cursor is obtained through the [`AlignedVec::write`] method.
-pub struct VecSpaceCursor<'vec, T> {
+pub struct AlignedVecCursor<'vec, T> {
     vec: &'vec mut AlignedVec<T>,
     allocated_length: usize,
 }
 
-impl<'vec, T: Copy + 'static> SpaceAllocator for VecSpaceCursor<'vec, T> {
+impl<'vec, T: Copy + 'static> SpaceAllocator for AlignedVecCursor<'vec, T> {
     fn allocate_and_split(
         &mut self,
         size: usize,

atom/src/unidentified.rs

@@ -5,7 +5,8 @@ use urid::URID;
 
 /// An atom of yet unknown type.
 ///
-/// This is used by reading handles that have to return a reference to an atom, but can not check it's type. This struct contains a `Space` containing the header and the body of the atom and can identify/read the atom from it.
+/// This is used by reading handles that have to return a reference to an atom, but cannot check its type.
+/// This struct contains a `Space` containing the header and the body of the atom and can identify/read the atom from it.
 #[repr(C)]
 pub struct UnidentifiedAtom {
     header: AtomHeader,

state/src/raw.rs

@@ -101,13 +101,13 @@ impl<'a> StoreHandle<'a> {
 
 /// Writing handle for properties.
 pub struct StatePropertyWriter<'a> {
-    cursor: VecSpaceCursor<'a, AtomHeader>,
+    cursor: AlignedVecCursor<'a, AtomHeader>,
     initialized: bool,
 }
 
 impl<'a> StatePropertyWriter<'a> {
     /// Create a new property writer that uses the given space head.
-    pub fn new(cursor: VecSpaceCursor<'a, AtomHeader>) -> Self {
+    pub fn new(cursor: AlignedVecCursor<'a, AtomHeader>) -> Self {
         Self {
             cursor,
             initialized: false,