Update rustdoc for state::merkle::sql

This change updates the doc for various structs and modules in the
state::merke::sql module.

Signed-off-by: Peter Schwarz <[email protected]>

libtransact/src/state/merkle/sql/backend/mod.rs

@@ -15,6 +15,10 @@
  * -----------------------------------------------------------------------------
  */
 
+//! Database Backends
+//!
+//! A Backend provides a light-weight abstraction over database connections.
+
 #[cfg(feature = "postgres")]
 pub(in crate::state::merkle::sql) mod postgres;
 #[cfg(feature = "sqlite")]
@@ -29,14 +33,22 @@ pub use postgres::{PostgresBackend, PostgresBackendBuilder, PostgresConnection};
 #[cfg(feature = "sqlite")]
 pub use sqlite::{JournalMode, SqliteBackend, SqliteBackendBuilder, SqliteConnection, Synchronous};
 
+/// A database connection.
 pub trait Connection {
+    /// The underlying internal connection.
     type ConnectionType: diesel::Connection;
 
+    /// Access the internal connection.
     fn as_inner(&self) -> &Self::ConnectionType;
 }
 
+/// A database backend.
+///
+/// A Backend provides a light-weight abstraction over database connections.
 pub trait Backend: Sync + Send {
+    /// The database connection.
     type Connection: Connection;
 
+    /// Acquire a database connection.
     fn connection(&self) -> Result<Self::Connection, InternalError>;
 }

libtransact/src/state/merkle/sql/backend/postgres.rs

@@ -15,12 +15,19 @@
  * -----------------------------------------------------------------------------
  */
 
+//! Postgres Database Backend
+//!
+//! Available if the feature "postgres" is enabled.
+
 use diesel::r2d2::{ConnectionManager, Pool, PooledConnection};
 
 use crate::error::{InternalError, InvalidStateError};
 
 use super::{Backend, Connection};
 
+/// A connection to a Postgres database.
+///
+/// Available if the feature "postgres" is enabled.
 pub struct PostgresConnection(
     pub(in crate::state::merkle::sql) PooledConnection<ConnectionManager<diesel::pg::PgConnection>>,
 );
@@ -35,7 +42,9 @@ impl Connection for PostgresConnection {
 
 /// The Postgres Backend
 ///
-/// This struct provides the backend implementation details for postgres databases.
+/// This struct provides the [Backend] implementation details for Postgres databases.
+///
+/// Available if the feature "postgres" is enabled.
 #[derive(Clone)]
 pub struct PostgresBackend {
     connection_pool: Pool<ConnectionManager<diesel::pg::PgConnection>>,
@@ -61,6 +70,8 @@ impl From<Pool<ConnectionManager<diesel::pg::PgConnection>>> for PostgresBackend
 }
 
 /// A Builder for the PostgresBackend.
+///
+/// Available if the feature "postgres" is enabled.
 #[derive(Default)]
 pub struct PostgresBackendBuilder {
     url: Option<String>,

libtransact/src/state/merkle/sql/backend/sqlite.rs

@@ -16,6 +16,8 @@
  */
 
 //! A Backend implementation for SQLite databases.
+//!
+//! Available if the feature "sqlite" is enabled.
 
 use std::convert::TryFrom;
 use std::fmt;
@@ -32,6 +34,8 @@ use crate::error::{InternalError, InvalidStateError};
 use super::{Backend, Connection};
 
 /// A connection to a SQLite database.
+///
+/// Available if the feature "sqlite" is enabled.
 pub struct SqliteConnection(
     pub(in crate::state::merkle::sql) PooledConnection<ConnectionManager<sqlite::SqliteConnection>>,
 );
@@ -47,6 +51,8 @@ impl Connection for SqliteConnection {
 /// The SQLite Backend
 ///
 /// This struct provides the backend implementation details for SQLite databases.
+///
+/// Available if the feature "sqlite" is enabled.
 #[derive(Clone)]
 pub struct SqliteBackend {
     connection_pool: Pool<ConnectionManager<sqlite::SqliteConnection>>,
@@ -78,6 +84,8 @@ pub const DEFAULT_MMAP_SIZE: i64 = 100 * 1024 * 1024;
 ///
 /// See the [PRAGMA "synchronous"](https://sqlite.org/pragma.html#pragma_journal_mode)
 /// documentation for more details.
+///
+/// Available if the feature "sqlite" is enabled.
 #[derive(Debug)]
 pub enum Synchronous {
     /// With synchronous Off, SQLite continues without syncing as soon as it has handed data
@@ -118,6 +126,8 @@ impl fmt::Display for Synchronous {
 ///
 /// See the [PRAGMA "journal_mode"](https://sqlite.org/pragma.html#pragma_journal_mode)
 /// documentation for more details.
+///
+/// Available if the feature "sqlite" is enabled.
 #[derive(Debug)]
 pub enum JournalMode {
     /// The DELETE journaling mode is the normal behavior. In the DELETE mode, the rollback journal
@@ -159,6 +169,9 @@ impl fmt::Display for JournalMode {
     }
 }
 
+/// A builder for a [SqliteBackend].
+///
+/// Available if the feature "sqlite" is enabled.
 pub struct SqliteBackendBuilder {
     connection_path: Option<String>,
     create: bool,
@@ -181,14 +194,15 @@ impl SqliteBackendBuilder {
         }
     }
 
-    /// Configures the SqliteBackend instance as a memory database, with a connection pool size of 1.
+    /// Configures the [SqliteBackend] instance as a memory database, with a connection pool size of
+    /// 1.
     pub fn with_memory_database(mut self) -> Self {
         self.connection_path = Some(":memory:".into());
         self.pool_size = Some(1);
         self
     }
 
-    /// Set the path for the Sqlite database.
+    /// Set the path for the SQLite database.
     ///
     /// This is a required field.
     pub fn with_connection_path<S: Into<String>>(mut self, connection_path: S) -> Self {
@@ -210,7 +224,7 @@ impl SqliteBackendBuilder {
 
     /// Set the size used for Memory-Mapped I/O.
     ///
-    /// This can be disabled by setting the value to `0`
+    /// This can be disabled by setting the value to `0`.
     pub fn with_memory_map_size(mut self, memory_map_size: u64) -> Self {
         // The try from would fail if the u64 is greater than max i64, so we can unwrap this as
         // such.

libtransact/src/state/merkle/sql/mod.rs

@@ -45,6 +45,8 @@
 //!
 //! The resulting `merkle_state` can then be used via the [`Read`], [`Write`] and
 //! [`MerkleRadixLeafReader`] traits.
+//!
+//! Available if the feature "state-merkle-sql" is enabled.
 
 pub mod backend;
 mod error;