Refine documentation

src/simple.rs

@@ -9,11 +9,21 @@ use rusqlite::Connection;
 use crate::{Action, Migration};
 
 /// A simple, single-threaded vault.
+///
+/// This vault may be useful if you want to re-use existing [`Action`]s and
+/// [`Migration`]s but don't need the additional guarantees and overhead of the
+/// other vaults.
 pub struct SimpleVault(Connection);
 
 impl SimpleVault {
     /// Create a new vault from an existing [`Connection`], applying the
     /// migrations in the process.
+    ///
+    /// It is recommended to set a few pragmas before calling this function, for
+    /// example:
+    /// - `journal_mode` to `"wal"`
+    /// - `foreign_keys` to `true`
+    /// - `trusted_schema` to `false`
     pub fn new(conn: Connection, migrations: &[Migration]) -> rusqlite::Result<Self> {
         Self::new_and_prepare(conn, migrations, |_| Ok(()))
     }
@@ -23,6 +33,12 @@ impl SimpleVault {
     ///
     /// The `prepare` parameter allows access to the database after all
     /// migrations have occurred. This parameter could be replaced by executing
+    ///
+    /// It is recommended to set a few pragmas before calling this function, for
+    /// example:
+    /// - `journal_mode` to `"wal"`
+    /// - `foreign_keys` to `true`
+    /// - `trusted_schema` to `false`
     /// an [`Action`] performing the same operations.
     pub fn new_and_prepare(
         mut conn: Connection,

src/tokio.rs

@@ -1,4 +1,4 @@
-//! A vault for use with `tokio`.
+//! A vault for use with [`tokio`].
 
 use std::{any::Any, result, thread};
 
@@ -64,7 +64,7 @@ fn run(mut conn: Connection, mut rx: mpsc::UnboundedReceiver<Command>) {
     }
 }
 
-/// A vault for use with `tokio`.
+/// A vault for use with [`tokio`].
 #[derive(Clone)]
 pub struct TokioVault {
     tx: mpsc::UnboundedSender<Command>,