From 6c3eeb1db2018733da5e3d424ac48b0cae5b814b Mon Sep 17 00:00:00 2001
From: Emi Tatsuo <emi@alchemi.dev>
Date: Tue, 8 Dec 2020 11:01:07 -0500
Subject: [PATCH] Document a few more types in the UserManagement module

---
 src/user_management/manager.rs | 12 ++++++++++++
 src/user_management/mod.rs     | 35 ++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/src/user_management/manager.rs b/src/user_management/manager.rs
index 009f802..c7b6bd6 100644
--- a/src/user_management/manager.rs
+++ b/src/user_management/manager.rs
@@ -8,6 +8,18 @@ use crate::user_management::user::{RegisteredUser, NotSignedInUser, PartialUser}
 ///
 /// Wraps a [`sled::Db`]
 pub struct UserManager {
+    /// Allows access to the [`sled::Db`] used by the UserManager to store user data.
+    ///
+    /// Do not try to use this database to access user information, and instead prefer
+    /// methods such as [`lookup_user()`] and [`lookup_certificate()`].
+    ///
+    /// However, you're welcome to use the database to store you own data without needing
+    /// to run parallel sled databases.  It's recommended that any trees you open be
+    /// namespaced like `tld.yourdomain.projectname.treename` in order to prevent
+    /// conflict.
+    ///
+    /// [`lookup_user()`]: Self::lookup_user
+    /// [`lookup_certificate()`]: Self::lookup_certificate
     pub db: sled::Db,
     pub (crate) users: sled::Tree, // user_id:String maps to data:UserData
     pub (crate) certificates: sled::Tree, // certificate:u64 maps to data:CertificateData
diff --git a/src/user_management/mod.rs b/src/user_management/mod.rs
index 288a65d..8dd8a44 100644
--- a/src/user_management/mod.rs
+++ b/src/user_management/mod.rs
@@ -33,14 +33,48 @@ use user::{NotSignedInUser, RegisteredUser};
 use crate::types::Request;
 
 #[derive(Debug)]
+/// An error that occured in the user manager
 pub enum UserManagerError {
+    /// Tried to set a user's username to a username that already exists
+    ///
+    /// Recommended handling: Explicitly catch the error, and display a custom warning to
+    /// the user before asking them to try another username
     UsernameNotUnique,
+
+    /// Attempted to validate the user's password, but they haven't set one yet
+    ///
+    /// Recommended handling: Inform the user that either their username or password was
+    /// incorrect.
     PasswordNotSet,
+
+    /// There was an error connecting to sled
+    ///
+    /// Recommended handling:  Log a visible error for the sysadmin to see, and exit
     DatabaseError(sled::Error),
+
+    /// There was an error running a database transaction
+    ///
+    /// Recommended handling:  Same as [`UserManagerError::DatabaseError`]
     DatabaseTransactionError(sled::transaction::TransactionError),
+
+    /// There was an error deserializing from the database
+    ///
+    /// This likely indicates that the database was generated with
+    /// a different version of the software than is curretly being used, either because
+    /// the UserData struct has changed, or because kochab itself has updated it's schema.
+    ///
+    /// Recommended handling:  Log a visible error and exit.  Recommend seeking a database
+    /// migration script or deleting the database
     DeserializeBincodeError(bincode::Error),
+
+    /// A different version of [`UserManagerError::DeserializeBincodeError`]
     DeserializeUtf8Error(std::str::Utf8Error),
+
     #[cfg(feature = "user_management_advanced")]
+    /// There was an error hashing or checking the user's password.
+    ///
+    /// This likely indicates database corruption, and should be handled in the same way
+    /// as a [`UserManagerError::DeserializeBincodeError`]
     Argon2Error(argon2::Error),
 }
 
@@ -111,4 +145,5 @@ impl std::fmt::Display for UserManagerError {
     }
 }
 
+/// A result type returned by many methods within the [`user_management`] module
 pub type Result<T> = std::result::Result<T, UserManagerError>;