diff --git a/heed-traits/src/lib.rs b/heed-traits/src/lib.rs index f1eb67a4..728ff247 100644 --- a/heed-traits/src/lib.rs +++ b/heed-traits/src/lib.rs @@ -1,3 +1,7 @@ +//! Crate `heed-traits` contains the traits used to encode and decode database content. + +#![warn(missing_docs)] + use std::borrow::Cow; use std::error::Error as StdError; @@ -6,14 +10,18 @@ pub type BoxedError = Box; /// A trait that represents an encoding structure. pub trait BytesEncode<'a> { + /// The type to encode type EItem: ?Sized + 'a; + /// Encode the given item as bytes fn bytes_encode(item: &'a Self::EItem) -> Result, BoxedError>; } /// A trait that represents a decoding structure. pub trait BytesDecode<'a> { + /// The type to decode type DItem: 'a; + /// Decode the given bytes as DItem fn bytes_decode(bytes: &'a [u8]) -> Result; } diff --git a/heed-types/src/integer.rs b/heed-types/src/integer.rs index 5edd1107..8c814b65 100644 --- a/heed-types/src/integer.rs +++ b/heed-types/src/integer.rs @@ -5,6 +5,7 @@ use std::mem::size_of; use byteorder::{ByteOrder, ReadBytesExt}; use heed_traits::{BoxedError, BytesDecode, BytesEncode}; +/// Encodable version of [`u8`] pub struct U8; impl BytesEncode<'_> for U8 { @@ -23,6 +24,7 @@ impl BytesDecode<'_> for U8 { } } +/// Encodable version of [`i8`] pub struct I8; impl BytesEncode<'_> for I8 { @@ -43,6 +45,10 @@ impl BytesDecode<'_> for I8 { macro_rules! define_type { ($name:ident, $native:ident, $read_method:ident, $write_method:ident) => { + #[doc = "Encodable version of [`"] + #[doc = stringify!($native)] + #[doc = "`]."] + pub struct $name(PhantomData); impl BytesEncode<'_> for $name { diff --git a/heed-types/src/lib.rs b/heed-types/src/lib.rs index 32ce9a28..24f0ea50 100644 --- a/heed-types/src/lib.rs +++ b/heed-types/src/lib.rs @@ -21,6 +21,8 @@ //! [`Serialize`]: serde::Serialize //! [`Deserialize`]: serde::Deserialize +#![warn(missing_docs)] + mod cow_slice; mod cow_type; mod integer; diff --git a/heed/src/lazy_decode.rs b/heed/src/lazy_decode.rs index 3ec3b64e..2843cea3 100644 --- a/heed/src/lazy_decode.rs +++ b/heed/src/lazy_decode.rs @@ -23,6 +23,7 @@ pub struct Lazy<'a, C> { } impl<'a, C: heed_traits::BytesDecode<'a>> Lazy<'a, C> { + /// Decode the given bytes as DItem pub fn decode(&self) -> Result { C::bytes_decode(self.data) } diff --git a/heed/src/lib.rs b/heed/src/lib.rs index b4b54a77..641d8455 100644 --- a/heed/src/lib.rs +++ b/heed/src/lib.rs @@ -46,6 +46,7 @@ //! assert_eq!(ret, Some(5)); //! # Ok(()) } //! ``` +#![warn(missing_docs)] mod cursor; mod db; @@ -79,12 +80,19 @@ pub use self::txn::{RoTxn, RwTxn}; /// An error that encapsulates all possible errors in this crate. #[derive(Debug)] pub enum Error { + /// I/O error: can come from the std or be a rewrapped [`MdbError`] Io(io::Error), + /// Lmdb error Mdb(MdbError), + /// Encoding error Encoding(BoxedError), + /// Decoding error Decoding(BoxedError), + /// Incoherent types when opening a database InvalidDatabaseTyping, + /// Database closing in progress DatabaseClosing, + /// Attempt to open Env with different options BadOpenOptions { /// The options that were used to originally open this env. options: EnvOpenOptions, diff --git a/heed/src/mdb/lmdb_error.rs b/heed/src/mdb/lmdb_error.rs index 11674b2f..068d8281 100644 --- a/heed/src/mdb/lmdb_error.rs +++ b/heed/src/mdb/lmdb_error.rs @@ -60,6 +60,7 @@ pub enum Error { } impl Error { + /// Return true if the given error is [`Error::NotFound`] pub fn not_found(&self) -> bool { *self == Error::NotFound } diff --git a/heed/src/mdb/lmdb_flags.rs b/heed/src/mdb/lmdb_flags.rs index 7e3b8780..05fb8788 100644 --- a/heed/src/mdb/lmdb_flags.rs +++ b/heed/src/mdb/lmdb_flags.rs @@ -4,15 +4,26 @@ use lmdb_master_sys as ffi; #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u32)] pub enum Flag { + /// mmap at a fixed address (experimental) Fixedmap = ffi::MDB_FIXEDMAP, + /// no environment directory NoSubDir = ffi::MDB_NOSUBDIR, + /// don't fsync after commit NoSync = ffi::MDB_NOSYNC, + /// read only RdOnly = ffi::MDB_RDONLY, + /// don't fsync metapage after commit NoMetaSync = ffi::MDB_NOMETASYNC, + /// use writable mmap WriteMap = ffi::MDB_WRITEMAP, + /// use asynchronous msync when MDB_WRITEMAP is used MapAsync = ffi::MDB_MAPASYNC, + /// tie reader locktable slots to MDB_txn objects instead of to threads NoTls = ffi::MDB_NOTLS, + /// don't do any locking, caller must manage their own locks NoLock = ffi::MDB_NOLOCK, + /// don't do readahead (no effect on Windows) NoRdAhead = ffi::MDB_NORDAHEAD, + /// don't initialize malloc'd memory before writing to datafile NoMemInit = ffi::MDB_NOMEMINIT, } diff --git a/heed/src/txn.rs b/heed/src/txn.rs index 3d1229c9..2dad0b37 100644 --- a/heed/src/txn.rs +++ b/heed/src/txn.rs @@ -76,12 +76,16 @@ impl<'p> RwTxn<'p> { self.txn.env.env_mut_ptr() } + /// Commit all the operations of a transaction into the database. + /// The transaction is reset. pub fn commit(mut self) -> Result<()> { let result = unsafe { mdb_result(ffi::mdb_txn_commit(self.txn.txn)) }; self.txn.txn = ptr::null_mut(); result.map_err(Into::into) } + /// Abandon all the operations of the transaction instead of saving them. + /// The transaction is reset. pub fn abort(mut self) { abort_txn(self.txn.txn); self.txn.txn = ptr::null_mut();