More docs

Author: Xiphoseer

modules/fdb-raw/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2018"
 
 [features]
-default = []
+default = ["bcast"]
 zero = ["zerovec"]
 pod = ["bytemuck", "bytemuck_derive"]
 bcast = ["bytes-cast"]

modules/fdb-raw/src/aligned.rs

@@ -1,13 +1,24 @@
+//! # "Normal" aligned versions of the FDB structures
+
 use crate::generic;
 
+/// The header at the start of the file
 pub type Header = generic::Header<u32, u32>;
+/// The entry in the table array
 pub type TableHeader = generic::Table<u32>;
+/// The definition of the data
 pub type TableDefHeader = generic::TableDef<u32, u32>;
+/// The data of a column
 pub type ColumnHeader = generic::Column<u32, u32>;
+/// The content of a table
 pub type TableDataHeader = generic::TableData<u32, u32>;
+/// The entry in the bucket list
 pub type BucketHeader = generic::BucketHeader<u32>;
+/// One element in the linked-list of rows
 pub type RowHeaderCons = generic::RowHeaderCons<u32>;
+/// The data for a row
 pub type RowHeader = generic::RowHeader<u32, u32>;
+/// One entry in the list of fields
 pub type FieldData = generic::FieldData<u32, [u8; 4]>;
 
 impl Header {

modules/fdb-raw/src/bcast.rs

@@ -0,0 +1,25 @@
+//! # Implementations for the [`bytes_cast`] crate
+//!
+//! [`bytes_cast`]: https://docs.rs/bytes-cast
+
+use crate::generic;
+use bytes_cast::unaligned::U32Le;
+
+/// The header of the file
+pub type Header = generic::Header<U32Le, U32Le>;
+/// One entry in the [`Header::tables`] array
+pub type TableHeader = generic::Table<U32Le>;
+/// The definition of a table
+pub type TableDefHeader = generic::TableDef<U32Le, U32Le>;
+/// One entry in the [`TableDefHeader::column_list`] array
+pub type ColumnHeader = generic::Column<U32Le, U32Le>;
+/// The contents of a table
+pub type TableDataHeader = generic::TableData<U32Le, U32Le>;
+/// One entry in the [`TableDataHeader::buckets`]
+pub type BucketHeader = generic::BucketHeader<U32Le>;
+/// One entry in the linked list of rows in a [`BucketHeader`]
+pub type RowHeaderCons = generic::RowHeaderCons<U32Le>;
+/// The data for a single row
+pub type RowHeader = generic::RowHeader<U32Le, U32Le>;
+/// One entry in the [`RowHeader::fields`] array
+pub type FieldData = generic::FieldData<U32Le, [u8; 4]>;

modules/fdb-raw/src/error.rs

@@ -1,3 +1,5 @@
+//! ## Error types
+
 use core::fmt;
 
 #[derive(Debug)]

modules/fdb-raw/src/generic.rs

@@ -13,6 +13,7 @@ pub struct Array<Addr, Len> {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// The header at the start of the file
 pub struct Header<Addr, Len> {
     /// The list of tables in the database
     ///
@@ -22,6 +23,7 @@ pub struct Header<Addr, Len> {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// One entry in the tables list
 pub struct Table<Addr> {
     /// The offset of this table definition header.
     pub def_header: Addr,
@@ -31,6 +33,7 @@ pub struct Table<Addr> {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// The definition of a table
 pub struct TableDef<Addr, Len> {
     /// The number of columns in this table.
     pub column_count: Len,
@@ -42,6 +45,7 @@ pub struct TableDef<Addr, Len> {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// One entry in a columns list
 pub struct Column<Addr, Ty> {
     /// The numeric identifier of the data type.
     pub data_type: Ty,
@@ -51,20 +55,23 @@ pub struct Column<Addr, Ty> {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// The content of a table
 pub struct TableData<Addr, Len> {
     /// The buckets.
     pub buckets: Array<Addr, Len>,
 }
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// One entry of the bucket list
 pub struct BucketHeader<Addr> {
     /// Offset of the first element of the linked list or 0xffffffff.
     pub head: Addr,
 }
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// One element of the linked list of rows
 pub struct RowHeaderCons<Addr> {
     /// The offset of the row header.
     pub first: Addr,
@@ -74,13 +81,15 @@ pub struct RowHeaderCons<Addr> {
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// The data for a single row
 pub struct RowHeader<Addr, Len> {
     /// The fields in this row
     pub fields: Array<Addr, Len>,
 }
 
 #[repr(C)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
+/// One entry in the fields list
 pub struct FieldData<Ty, Val> {
     /// The data type.
     pub data_type: Ty,

modules/fdb-raw/src/lib.rs

@@ -1,4 +1,4 @@
-#![allow(clippy::upper_case_acronyms)]
+#![warn(missing_docs)]
 //! The structures, as they are serialized
 //!
 //! This module contains the low-level structs that make up the FDB file. These
@@ -11,11 +11,11 @@
 //! covers the whole 32 bits.
 
 pub mod aligned;
+#[cfg(feature = "bcast")]
+pub mod bcast;
 pub mod error;
 pub mod generic;
 mod map;
-#[cfg(feature = "bcast")]
-pub mod unaligned;
 #[cfg(feature = "zero")]
 pub mod zero;
 
@@ -25,7 +25,14 @@ use bytemuck_derive::{Pod, Zeroable};
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "pod", derive(Pod, Zeroable))]
 #[repr(C)]
-pub struct FDBFieldValue(pub [u8; 4]);
+/// The value of a single field
+pub struct FieldValue(pub [u8; 4]);
+
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[cfg_attr(feature = "pod", derive(Pod, Zeroable))]
+#[repr(C)]
+/// A 32-bit offset into a file
+pub struct Offset(pub u32);
 
 #[cfg(test)]
 mod tests {

modules/fdb-raw/src/unaligned.rs

@@ -1,4 +1,8 @@
-use crate::{error::ModuloMismatch, generic, FDBFieldValue};
+//! # Implementations for the [`zerovec`] crate
+//!
+//! [`zerovec`]: https://docs.rs/zerovec
+
+use crate::{error::ModuloMismatch, generic, Offset};
 use zerovec::ule::{AsULE, EqULE, PlainOldULE, ULE};
 
 macro_rules! as_ule {
@@ -19,7 +23,7 @@ macro_rules! as_ule {
     };
 }
 
-impl AsULE for FDBFieldValue {
+impl AsULE for super::FieldValue {
     type ULE = FieldValueULE;
 
     fn as_unaligned(&self) -> Self::ULE {
@@ -41,42 +45,31 @@ as_ule!(crate::aligned::RowHeaderCons = RowHeaderConsULE);
 as_ule!(crate::aligned::RowHeader = RowHeaderULE);
 as_ule!(crate::aligned::FieldData = FieldDataULE);
 
-macro_rules! ule_alias(
-    ($ty:ty => $name:ident $ule:ident) => {
-        #[cfg(feature = "pod")]
-        use bytemuck_derive::{Pod, Zeroable};
-
-        #[derive(Copy, Clone, Debug, PartialEq, Eq)]
-        #[cfg_attr(feature = "pod", derive(Pod, Zeroable))]
-        #[repr(C)]
-        pub struct $name(pub $ty);
-
-        impl AsULE for $name {
-            type ULE = $ule;
-
-            fn as_unaligned(&self) -> Self::ULE {
-                self.0.as_unaligned().into()
-            }
+impl AsULE for Offset {
+    type ULE = OffsetULE;
 
-            fn from_unaligned(unaligned: &Self::ULE) -> Self {
-                Self(<$ty>::from_unaligned(unaligned.into()))
-            }
-        }
+    fn as_unaligned(&self) -> Self::ULE {
+        self.0.as_unaligned().into()
     }
-);
 
-ule_alias!(u32 => Offset OffsetULE);
+    fn from_unaligned(unaligned: &Self::ULE) -> Self {
+        let p: &PlainOldULE<4> = unaligned.into();
+        Self(u32::from_unaligned(p))
+    }
+}
 
 impl Offset {
+    /// Get the value as an usize
     pub fn usize(self) -> usize {
         self.0 as usize
     }
 }
 
 macro_rules! ule_alias(
-    ($name:ident<$size:literal>) => {
+    ($($doc:literal)? $name:ident<$size:literal>) => {
         #[repr(C)]
         #[derive(Copy, Clone, Debug)]
+        $(#[doc = $doc])?
         pub struct $name(pub(super) [u8; $size]);
 
         impl From<PlainOldULE<$size>> for $name {
@@ -93,8 +86,8 @@ macro_rules! ule_alias(
     };
 );
 
-ule_alias!(OffsetULE<4>);
-ule_alias!(ULE32<4>);
+ule_alias!("OffsetULE" OffsetULE<4>);
+ule_alias!("ULE32" ULE32<4>);
 
 impl From<u32> for OffsetULE {
     fn from(v: u32) -> Self {
@@ -155,14 +148,23 @@ ule_impl!(
     RowHeaderConsULE FieldDataULE FieldValueULE
 );
 
+/// The header at the beginning of the file
 pub type HeaderULE = generic::Header<OffsetULE, ULE32>;
+/// One entry in the table array
 pub type TableHeaderULE = generic::Table<OffsetULE>;
+/// The definition of a table
 pub type TableDefHeaderULE = generic::TableDef<OffsetULE, ULE32>;
+/// One entry in the column array
 pub type ColumnHeaderULE = generic::Column<OffsetULE, ULE32>;
+/// The content of a table
 pub type TableDataHeaderULE = generic::TableData<OffsetULE, ULE32>;
+/// One entry in the buckets array
 pub type BucketHeaderULE = generic::BucketHeader<OffsetULE>;
+/// One entry in the linked-list of rows
 pub type RowHeaderConsULE = generic::RowHeaderCons<OffsetULE>;
+/// The data for a single row
 pub type RowHeaderULE = generic::RowHeader<OffsetULE, ULE32>;
+/// One entry in the list of fields
 pub type FieldDataULE = generic::FieldData<ULE32, FieldValueULE>;
 
 /// An FDB field value usable for unaligned reads