doc: add documentation

Cargo.lock

@@ -493,7 +493,7 @@ checksum = "692fcb63b64b1758029e0a96ee63e049ce8c5948587f2f7208df04625e5f6b56"
 
 [[package]]
 name = "ood_persistence"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "bb8",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ood_persistence"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2018"
 authors = ["Dmitriy Pleshevskiy <dmitriy@ideascup.me>"]
 repository = "https://github.com/pleshevskiy/ood_persistence"

src/asyn.rs

@@ -1,29 +1,66 @@
 use crate::error;
 
+/// The pool is one of the main features to be realized in persistence.
+///
+/// Any implementation (database, file storage, memory or others) must be able to get a connection
+/// to manipulate it afterwards.
 #[async_trait]
 pub trait PersistencePool: Send + Sync {
+    /// ConnectionClient implementation that persistence can can return.
     type Conn: ConnectionClient;
 
+    /// Returns new connection.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if pool cannot get a connection.
     async fn get_connection(&self) -> error::Result<Self::Conn>;
 }
 
+/// Connection client knows about the inner connection, and also knows how to create transactions.
 #[cfg_attr(feature = "nightly", async_trait)]
 pub trait ConnectionClient {
+    /// Inner connection
     type InnerConn;
 
+    /// TransactionClient implementation in which the connection can be updated.
+    ///
+    /// **Note:** requires nightly rust channel and enabling the `nightly` feature.
     #[cfg(feature = "nightly")]
     type Trx<'t>: TransactionClient;
 
+    /// Returns inner connection
     fn inner(&mut self) -> &mut Self::InnerConn;
 
+    /// Updates connection to transaction.
+    ///
+    /// **Note:** requires nightly rust channel and enabling the `nightly` feature.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if connection cannot update to transaction.
     #[cfg(feature = "nightly")]
     async fn start_transaction(&mut self) -> error::Result<Self::Trx<'_>>;
 }
 
+/// Transaction client is updated connection client that can additionally commit and rollback data
+/// in transactions.
+///
+/// **Note:** requires nightly rust channel and enabling the `nightly` feature.
 #[cfg(feature = "nightly")]
 #[async_trait]
 pub trait TransactionClient: ConnectionClient {
+    /// Consumes the transaction, committing all changes made within it.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if transaction cannot commit
     async fn commit(self) -> error::Result<()>;
 
+    /// Rolls the transaction back, discarding all changes made within it.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if transaction cannot rolls back.
     async fn rollback(self) -> error::Result<()>;
 }

src/bb8_postgres.rs

@@ -7,15 +7,23 @@ pub use bb8::{Pool, PooledConnection};
 pub use bb8_postgres::tokio_postgres;
 pub use bb8_postgres::PostgresConnectionManager as Manager;
 
+/// Inner connection of bb8 implementation.
 pub type InnerConn<'p, M> = PooledConnection<'p, M>;
+/// Inner connection of tokio postgres connection.
 pub type InnerTrx<'p> = tokio_postgres::Transaction<'p>;
 
+/// Alias for bb8 postgres no tls manager.
 pub type NoTlsManager = Manager<tokio_postgres::NoTls>;
+/// Alias for bb8 postgres no tls persistence.
 pub type NoTlsPersistence<'p> = Persistence<'p, NoTlsManager>;
+/// Alias for bb8 postgres no tls connection.
 pub type NoTlsConnection<'p> = Connection<'p, NoTlsManager>;
+/// Alias for bb8 postgres no tls inner connection.
 pub type NoTlsInnerConn<'p> = InnerConn<'p, NoTlsManager>;
+/// Alias for bb8 postgres no tls pool.
 pub type NoTlsPool = Pool<NoTlsManager>;
 
+/// It creates new persistence of bb8 postgres implementation.
 #[must_use]
 pub fn new<M>(pool: &Pool<M>) -> Persistence<M>
 where
@@ -24,6 +32,7 @@ where
     Persistence(pool)
 }
 
+/// Persistence wrap over bb8 pool.
 #[derive(Clone)]
 pub struct Persistence<'p, M>(&'p Pool<M>)
 where
@@ -42,6 +51,7 @@ impl<'p> PersistencePool for NoTlsPersistence<'p> {
     }
 }
 
+/// Connection wrap over bb8 postgres inner connection.
 pub struct Connection<'p, M>(InnerConn<'p, M>)
 where
     M: bb8::ManageConnection;
@@ -67,6 +77,9 @@ impl<'me> ConnectionClient for NoTlsConnection<'me> {
     }
 }
 
+/// Transaction wrap over tokio_postgres transaction.
+///
+/// **Note:** requires nightly rust channel and enabling the `nightly` feature.
 #[cfg(feature = "nightly")]
 pub struct Transaction<'p>(InnerTrx<'p>);
 

src/r2d2_postgres.rs

@@ -7,15 +7,23 @@ pub use r2d2::{Pool, PooledConnection};
 pub use r2d2_postgres::postgres;
 pub use r2d2_postgres::PostgresConnectionManager as Manager;
 
+/// Inner connection of r2d2 implementation.
 pub type InnerConn<M> = PooledConnection<M>;
+/// Inner connection of postgres connection.
 pub type InnerTrx<'t> = postgres::Transaction<'t>;
 
+/// Alias for r2d2 postgres no tls manager.
 pub type NoTlsManager = Manager<postgres::NoTls>;
+/// Alias for r2d2 postgres no tls persistence.
 pub type NoTlsPersistence<'p> = Persistence<'p, NoTlsManager>;
+/// Alias for r2d2 postgres no tls connection.
 pub type NoTlsConnection = Connection<NoTlsManager>;
+/// Alias for r2d2 postgres no tls inner connection.
 pub type NoTlsInnerConn = InnerConn<NoTlsManager>;
+/// Alias for r2d2 postgres no tls pool.
 pub type NoTlsPool = Pool<NoTlsManager>;
 
+/// It creates new persistence of r2d2 postgres implementation.
 pub fn new<M>(pool: &Pool<M>) -> Persistence<M>
 where
     M: r2d2::ManageConnection,
@@ -23,6 +31,7 @@ where
     Persistence(pool)
 }
 
+/// Persistence wrap over r2d2 pool.
 #[derive(Clone)]
 pub struct Persistence<'p, M>(&'p Pool<M>)
 where
@@ -39,6 +48,7 @@ impl<'p> PersistencePool for NoTlsPersistence<'p> {
     }
 }
 
+/// Connection wrap over r2d2 postgres inner connection.
 pub struct Connection<M>(InnerConn<M>)
 where
     M: r2d2::ManageConnection;
@@ -62,6 +72,9 @@ impl ConnectionClient for NoTlsConnection {
     }
 }
 
+/// Transaction wrap over postgres transaction.
+///
+/// **Note:** requires nightly rust channel and enabling the `nightly` feature.
 #[cfg(feature = "nightly")]
 pub struct Transaction<'me>(InnerTrx<'me>);
 

src/syn.rs

@@ -1,26 +1,63 @@
 use crate::error;
 
+/// The pool is one of the main features to be realized in persistence.
+///
+/// Any implementation (database, file storage, memory or others) must be able to get a connection
+/// to manipulate it afterwards.
 pub trait PersistencePool {
+    /// ConnectionClient implementation that persistence can can return.
     type Conn: ConnectionClient;
 
+    /// Returns new connection.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if pool cannot get a connection.
     fn get_connection(&self) -> error::Result<Self::Conn>;
 }
 
+/// Connection client knows about the inner connection, and also knows how to create transactions.
 pub trait ConnectionClient {
+    /// Inner connection
     type InnerConn;
 
+    /// TransactionClient implementation in which the connection can be updated.
+    ///
+    /// **Note:** requires nightly rust channel and enabling the `nightly` feature.
     #[cfg(feature = "nightly")]
     type Trx<'t>: TransactionClient;
 
+    /// Returns inner connection
     fn inner(&mut self) -> &mut Self::InnerConn;
 
+    /// Updates connection to transaction.
+    ///
+    /// **Note:** requires nightly rust channel and enabling the `nightly` feature.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if connection cannot update to transaction.
     #[cfg(feature = "nightly")]
     fn start_transaction(&mut self) -> error::Result<Self::Trx<'_>>;
 }
 
+/// Transaction client is updated connection client that can additionally commit and rollback data
+/// in transactions.
+///
+/// **Note:** requires nightly rust channel and enabling the `nightly` feature.
 #[cfg(feature = "nightly")]
 pub trait TransactionClient: ConnectionClient {
+    /// Consumes the transaction, committing all changes made within it.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if transaction cannot commit
     fn commit(self) -> error::Result<()>;
 
+    /// Rolls the transaction back, discarding all changes made within it.
+    ///
+    /// # Errors
+    ///
+    /// Returns PersistenceError if transaction cannot rolls back.
     fn rollback(self) -> error::Result<()>;
 }