Add missing documentation.

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<dyn StdError + Send + Sync + 'static>;
 
 /// 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<Cow<'a, [u8]>, 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<Self::DItem, BoxedError>;
 }

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<O>(PhantomData<O>);
 
         impl<O: ByteOrder> BytesEncode<'_> for $name<O> {

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;

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::DItem, BoxedError> {
         C::bytes_decode(self.data)
     }

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,

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
     }

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,
 }

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();