some docs

calibre-db/src/calibre.rs

@@ -24,83 +24,107 @@ pub struct Calibre {
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when loading the calibre database.
 pub enum LoadError {
+    /// A failure to create the database connection pool.
     #[snafu(display("Failed to create database connection pool."))]
     CreateDbPool { source: r2d2::Error },
+    /// A failure to create the temporary database view.
     #[snafu(display("Failed to create temporary database view."))]
     TmpDb { source: io::Error },
+    /// A failure to keep the temporary database from being deleted.
     #[snafu(display("Failed to keep temporary database from deletion."))]
     PersistTmpDb { source: PersistError },
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when accessing the data store.
 pub enum DataStoreError {
+    /// A failure to get a database connection from the pool.
     #[snafu(display("Failed to get database connection from pool."))]
     GetDbConn { source: r2d2::Error },
 
+    /// A failure during a search operation.
     #[snafu(display("Failed to search."))]
     Search { source: crate::search::SearchError },
 
+    /// A failure to fetch multiple books.
     #[snafu(display("Failed to fetch multiple books."))]
     MultipleBooks {
         source: data::book::MultipleBooksError,
     },
+    /// A failure to fetch recent books.
     #[snafu(display("Failed to fetch recent books."))]
     RecentBooks {
         source: data::book::RecentBooksError,
     },
+    /// A failure to fetch a single book.
     #[snafu(display("Failed to fetch book."))]
     ScalarBook { source: data::book::ScalarBookError },
+    /// A failure to get a series' books.
     #[snafu(display("Failed to get a series' books."))]
     SeriesBooks { source: data::book::SeriesBookError },
+    /// A failure to fetch an author's books.
     #[snafu(display("Failed to fetch an author's books."))]
     AuthorBooks {
         source: data::book::AuthorBooksError,
     },
+    /// A failure to check for previous books.
     #[snafu(display("Failed to check if there are previous books."))]
     HasPreviousBooks {
         source: data::book::PreviousBooksError,
     },
+    /// A failure to check for more books.
     #[snafu(display("Failed to check if there are more books."))]
     HasMoreBooks { source: data::book::MoreBooksError },
 
+    /// A failure to fetch multiple authors.
     #[snafu(display("Failed to fetch multiple authors."))]
     MultipleAuthors {
         source: data::author::MultipleAuthorsError,
     },
+    /// A failure to fetch a single author.
     #[snafu(display("Failed to fetch author."))]
     ScalarAuthor {
         source: data::author::ScalarAuthorError,
     },
+    /// A failure to fetch a book's author.
     #[snafu(display("Failed to fetch book's author."))]
     BookAuthor {
         source: data::author::BookAuthorError,
     },
+    /// A failure to check for previous authors.
     #[snafu(display("Failed to check if there are previous authors."))]
     HasPreviousAuthors {
         source: data::author::PreviousAuthorsError,
     },
+    /// A failure to check for more authors.
     #[snafu(display("Failed to check if there are more authors."))]
     HasMoreAuthors {
         source: data::author::MoreAuthorsError,
     },
 
+    /// A failure to fetch multiple series.
     #[snafu(display("Failed to fetch multiple series."))]
     MultipleSeries {
         source: data::series::MultiplSeriesError,
     },
+    /// A failure to fetch a single series.
     #[snafu(display("Failed to fetch series."))]
     ScalarSeries {
         source: data::series::ScalarSeriesError,
     },
+    /// A failure to get the series a book belongs to.
     #[snafu(display("Failed to get the series a book belongs to."))]
     BookSeries {
         source: data::series::SeriesBooksError,
     },
+    /// A failure to check for previous series.
     #[snafu(display("Failed to check if there are previous series."))]
     HasPreviousSeries {
         source: data::series::PreviousSeriesError,
     },
+    /// A failure to check for more series.
     #[snafu(display("Failed to check if there are more series."))]
     HasMoreSeries {
         source: data::series::MoreSeriesError,

calibre-db/src/data/pagination.rs

@@ -26,17 +26,23 @@ pub struct Pagination<'a> {
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when checking for previous or more items.
 pub enum HasPrevOrMoreError {
+    /// A failure to prepare the SQL statement.
     #[snafu(display("Failed to prepare statement."))]
     PrepareHasPrevOrMore { source: rusqlite::Error },
+    /// A failure to execute the SQL statement.
     #[snafu(display("Failed to execute statement."))]
     ExecuteHasPrevOrMore { source: rusqlite::Error },
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur during pagination.
 pub enum PaginationError {
+    /// A failure to prepare the SQL statement.
     #[snafu(display("Failed to prepare statement."))]
     PreparePagination { source: rusqlite::Error },
+    /// A failure to execute the SQL statement.
     #[snafu(display("Failed to execute statement."))]
     ExecutePagination { source: rusqlite::Error },
 }

little-hesinde/src/api/download.rs

@@ -8,7 +8,9 @@ use tokio::io::AsyncRead;
 use tokio_util::io::ReaderStream;
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when downloading a file.
 pub enum DownloadError {
+    /// A failure to construct the response body.
     #[snafu(display("Failed to fetch cover."))]
     Body { source: http::Error },
 }

little-hesinde/src/api/html/books.rs

@@ -1,3 +1,4 @@
+//! Handle requests for books.
 use std::{io, sync::Arc};
 
 use axum::{
@@ -22,7 +23,9 @@ use crate::{
 };
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when retrieving books.
 pub enum RetrieveError {
+    /// A failure to fetch pagination data.
     #[snafu(display("Failed to fetch pagination data."))]
     Books { source: BookError },
 }
@@ -69,11 +72,14 @@ pub async fn handler(
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when fetching a book.
 pub enum BookError {
+    /// A failure to fetch pagination data.
     #[snafu(display("Failed to fetch pagination data."))]
     Pagination { source: PaginationError },
 }
 
+/// Render a paginated list of books.
 async fn books(
     state: &Arc<AppState>,
     cursor: Option<&str>,
@@ -101,13 +107,18 @@ async fn books(
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when downloading a book.
 pub enum DownloadError {
+    /// A failure to fetch book data.
     #[snafu(display("Failed to fetch book data."))]
     BookData { source: DataStoreError },
+    /// The requested book was not found.
     #[snafu(display("No such book."))]
     NotFound,
+    /// The requested book file was not found.
     #[snafu(display("No such book."))]
     FileNotFound { source: io::Error },
+    /// A failure to stream the book file.
     #[snafu(display("Failed to stream book file."))]
     Stream { source: download::DownloadError },
 }

little-hesinde/src/api/html/cover.rs

@@ -1,3 +1,4 @@
+//! Handle requests for book covers.
 use std::{fs::File, io, path::Path as FilePath, sync::Arc};
 
 use axum::{
@@ -21,9 +22,12 @@ use crate::{
 };
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when retrieving a cover.
 pub enum RetrieveError {
+    /// A failure to fetch the cover.
     #[snafu(display("Failed to fetch cover."))]
     Cover { source: CoverError },
+    /// A failure to open the cover file.
     #[snafu(display("Failed to open cover."))]
     CoverOpen { source: io::Error },
 }
@@ -88,23 +92,31 @@ pub async fn full(
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when fetching a cover.
 pub enum CoverError {
+    /// A failure to fetch book data.
     #[snafu(display("Failed to fetch book data."))]
     BookData { source: DataStoreError },
+    /// The requested cover was not found.
     #[snafu(display("No such cover"))]
     NotFound { source: CoverFetchError },
-    #[snafu(display("Failed to fetch cover thumbnail."))]
+    /// A failure to stream the cover.
+    #[snafu(display("Failed to stream cover."))]
     StreamCover { source: DownloadError },
 }
 
 #[derive(Debug, Snafu)]
+/// Errors that can occur when fetching a cover file.
 pub enum CoverFetchError {
+    /// A failure to fetch the cover thumbnail.
     #[snafu(display("Failed to fetch cover thumbnail."))]
     Thumbnail { source: RetrieveThumbnailError },
+    /// A failure to open the cover file.
     #[snafu(display("Failed to open cover file."))]
     FileOpen { source: io::Error },
 }
 
+/// Generic cover handler.
 async fn cover<F>(
     calibre: &Calibre,
     library_path: &FilePath,

little-hesinde/src/lib.rs

@@ -21,9 +21,9 @@ pub mod data;
 pub mod opds;
 pub mod templates;
 
-// App name from Cargo.toml
+/// The application name.
 const APP_NAME: &str = env!("CARGO_PKG_NAME");
-// Version from Cargo.toml
+/// The application version.
 const APP_VERSION: &str = env!("CARGO_PKG_VERSION");
 
 /// Internal marker data in lieu of a proper `Accept` header.