storage: document all the repository traits and methods

crates/storage-pg/src/lib.rs

@@ -13,25 +13,29 @@
 // limitations under the License.
 
 //! An implementation of the storage traits for a PostgreSQL database
+//!
+//! This backend uses [`sqlx`] to interact with the database. Most queries are
+//! type-checked, using introspection data recorded in the `sqlx-data.json`
+//! file. This file is generated by the `sqlx` CLI tool, and should be updated
+//! whenever the database schema changes, or new queries are added.
 
 #![forbid(unsafe_code)]
 #![deny(
     clippy::all,
     clippy::str_to_string,
     clippy::future_not_send,
-    rustdoc::broken_intra_doc_links
+    rustdoc::broken_intra_doc_links,
+    missing_docs
 )]
 #![warn(clippy::pedantic)]
-#![allow(
-    clippy::missing_errors_doc,
-    clippy::missing_panics_doc,
-    clippy::module_name_repetitions
-)]
+#![allow(clippy::module_name_repetitions)]
 
 use sqlx::{migrate::Migrator, postgres::PgQueryResult};
 use thiserror::Error;
 use ulid::Ulid;
 
+/// An extension trait for [`Result`] which adds a [`to_option`] method, useful
+/// for handling "not found" errors from [`sqlx`]
 trait LookupResultExt {
     type Output;
 
@@ -57,7 +61,11 @@ impl<T> LookupResultExt for Result<T, sqlx::Error> {
 #[error(transparent)]
 pub enum DatabaseError {
     /// An error which came from the database itself
-    Driver(#[from] sqlx::Error),
+    Driver {
+        /// The underlying error from the database driver
+        #[from]
+        source: sqlx::Error,
+    },
 
     /// An error which occured while converting the data from the database
     Inconsistency(#[from] DatabaseInconsistencyError),
@@ -66,6 +74,7 @@ pub enum DatabaseError {
     /// invalid
     #[error("Invalid database operation")]
     InvalidOperation {
+        /// The source of the error, if any
         #[source]
         source: Option<Box<dyn std::error::Error + Send + Sync + 'static>>,
     },
@@ -73,7 +82,13 @@ pub enum DatabaseError {
     /// An error which happens when an operation affects not enough or too many
     /// rows
     #[error("Expected {expected} rows to be affected, but {actual} rows were affected")]
-    RowsAffected { expected: u64, actual: u64 },
+    RowsAffected {
+        /// How many rows were expected to be affected
+        expected: u64,
+
+        /// How many rows were actually affected
+        actual: u64,
+    },
 }
 
 impl DatabaseError {
@@ -100,12 +115,19 @@ impl DatabaseError {
     }
 }
 
+/// An error which occured while converting the data from the database
 #[derive(Debug, Error)]
 pub struct DatabaseInconsistencyError {
+    /// The table which was being queried
     table: &'static str,
+
+    /// The column which was being queried
     column: Option<&'static str>,
+
+    /// The row which was being queried
     row: Option<Ulid>,
 
+    /// The source of the error
     #[source]
     source: Option<Box<dyn std::error::Error + Send + Sync + 'static>>,
 }
@@ -125,6 +147,7 @@ impl std::fmt::Display for DatabaseInconsistencyError {
 }
 
 impl DatabaseInconsistencyError {
+    /// Create a new [`DatabaseInconsistencyError`] for the given table
     #[must_use]
     pub(crate) const fn on(table: &'static str) -> Self {
         Self {
@@ -135,18 +158,22 @@ impl DatabaseInconsistencyError {
         }
     }
 
+    /// Set the column which was being queried
     #[must_use]
     pub(crate) const fn column(mut self, column: &'static str) -> Self {
         self.column = Some(column);
         self
     }
 
+    /// Set the row which was being queried
     #[must_use]
     pub(crate) const fn row(mut self, row: Ulid) -> Self {
         self.row = Some(row);
         self
     }
 
+    /// Give the source of the error
+    #[must_use]
     pub(crate) fn source<E: std::error::Error + Send + Sync + 'static>(
         mut self,
         source: E,
@@ -158,11 +185,12 @@ impl DatabaseInconsistencyError {
 
 pub mod compat;
 pub mod oauth2;
+pub mod upstream_oauth2;
+pub mod user;
+
 pub(crate) mod pagination;
 pub(crate) mod repository;
 pub(crate) mod tracing;
-pub mod upstream_oauth2;
-pub mod user;
 
 pub use self::repository::PgRepository;