From f37b4aa81ca82c11f73b917f2b20d88e34daf5e6 Mon Sep 17 00:00:00 2001
From: Joscha <joscha@plugh.de>
Date: Thu, 15 Dec 2022 11:17:09 +0100
Subject: [PATCH] Document more things

---
 src/lib.rs   |  7 +++++++
 src/tokio.rs | 11 +++++++----
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index c1c81fc..eb2799e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -14,6 +14,13 @@ pub mod tokio;
 
 use rusqlite::Connection;
 
+/// An action that can be performed on a [`Connection`].
+///
+/// Both commands and queries are considered actions. Commands usually have a
+/// return type of `()`, while queries return the result of the query.
+///
+/// Actions are usually passed to a vault which will then execute them and
+/// return the result. The way in which this occurs depends on the vault.
 pub trait Action {
     type Result;
     fn run(self, conn: &mut Connection) -> rusqlite::Result<Self::Result>;
diff --git a/src/tokio.rs b/src/tokio.rs
index f5ef879..528b491 100644
--- a/src/tokio.rs
+++ b/src/tokio.rs
@@ -1,3 +1,5 @@
+//! A vault for use with `tokio`.
+
 use std::{any::Any, result, thread};
 
 use rusqlite::{Connection, Transaction};
@@ -35,8 +37,8 @@ enum Command {
 /// Error that can occur during execution of an [`Action`].
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
-    /// The vault thread has stopped.
-    #[error("vault thread has stopped")]
+    /// The vault's thread has been stopped and its sqlite connection closed.
+    #[error("vault has been stopped")]
     Stopped,
 
     /// A [`rusqlite::Error`] occurred while running the action.
@@ -92,6 +94,7 @@ fn run(mut conn: Connection, mut rx: mpsc::UnboundedReceiver<Command>) {
     }
 }
 
+/// A vault for use with `tokio`.
 #[derive(Clone)]
 pub struct TokioVault {
     tx: mpsc::UnboundedSender<Command>,
@@ -158,9 +161,9 @@ impl TokioVault {
         Ok(*result)
     }
 
-    /// Stop the vault thread.
+    /// Stop the vault's thread and close its sqlite connection.
     ///
-    /// Returns when the vault has been stopped successfully.
+    /// Returns once the vault has been stopped.
     pub async fn stop(&self) {
         let (tx, rx) = oneshot::channel();
         let _ = self.tx.send(Command::Stop(tx));