From 41206abac102f3e12d0ca5b5b0fbf09941a333ea Mon Sep 17 00:00:00 2001 From: Sebastian Hugentobler Date: Wed, 2 Jul 2025 21:57:44 +0200 Subject: [PATCH] some more docs --- calibre-db/src/calibre.rs | 1 + calibre-db/src/data.rs | 1 + calibre-db/src/data/author.rs | 7 +++++++ calibre-db/src/data/book.rs | 10 ++++++++++ calibre-db/src/data/series.rs | 7 +++++++ calibre-db/src/search.rs | 15 +++++++++++++++ little-hesinde/build.rs | 1 + little-hesinde/src/api.rs | 1 + little-hesinde/src/api/authors.rs | 4 ++++ little-hesinde/src/api/books.rs | 3 +++ little-hesinde/src/api/html.rs | 1 + little-hesinde/src/api/html/archive.rs | 2 ++ little-hesinde/src/api/html/authors.rs | 8 ++++++++ little-hesinde/src/api/html/search.rs | 1 + little-hesinde/src/api/html/series.rs | 8 ++++++++ little-hesinde/src/api/opds.rs | 1 + little-hesinde/src/api/opds/authors.rs | 6 ++++++ little-hesinde/src/api/opds/books.rs | 5 +++++ little-hesinde/src/api/opds/recent.rs | 3 +++ little-hesinde/src/api/opds/search.rs | 7 +++++++ little-hesinde/src/api/opds/series.rs | 6 ++++++ little-hesinde/src/api/paginated.rs | 5 +++++ little-hesinde/src/api/recent.rs | 0 little-hesinde/src/api/search.rs | 3 +++ little-hesinde/src/api/series.rs | 4 ++++ little-hesinde/src/api/static_files.rs | 1 + little-hesinde/src/config.rs | 5 +++++ little-hesinde/src/data.rs | 1 + little-hesinde/src/opds/search.rs | 2 ++ 29 files changed, 119 insertions(+) create mode 100644 little-hesinde/src/api/recent.rs diff --git a/calibre-db/src/calibre.rs b/calibre-db/src/calibre.rs index a83d9f8..6e9f065 100644 --- a/calibre-db/src/calibre.rs +++ b/calibre-db/src/calibre.rs @@ -283,6 +283,7 @@ impl Calibre { } #[cfg(test)] +/// Tests for the calibre module. mod tests { use super::*; diff --git a/calibre-db/src/data.rs b/calibre-db/src/data.rs index 3663634..3b2a959 100644 --- a/calibre-db/src/data.rs +++ b/calibre-db/src/data.rs @@ -1,3 +1,4 @@ +//! Data types and functions for interacting with the calibre database. pub mod author; pub mod book; pub mod error; diff --git a/calibre-db/src/data/author.rs b/calibre-db/src/data/author.rs index 6a65c1b..d9f7253 100644 --- a/calibre-db/src/data/author.rs +++ b/calibre-db/src/data/author.rs @@ -24,17 +24,23 @@ pub struct MultipleAuthorsError { } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a book's author. pub enum BookAuthorError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareBookAuthor { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteBookAuthor { source: rusqlite::Error }, } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a single author. pub enum ScalarAuthorError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareScalarAuthor { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteScalarAuthor { source: rusqlite::Error }, } @@ -52,6 +58,7 @@ pub struct MoreAuthorsError { } impl Author { + /// Create an author from a database row. fn from_row(row: &Row<'_>) -> Result { Ok(Self { id: row.get(0)?, diff --git a/calibre-db/src/data/book.rs b/calibre-db/src/data/book.rs index f1824de..61a4af7 100644 --- a/calibre-db/src/data/book.rs +++ b/calibre-db/src/data/book.rs @@ -39,25 +39,34 @@ pub struct AuthorBooksError { } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a series' books. pub enum SeriesBookError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareSeriesBook { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteSeriesBook { source: rusqlite::Error }, } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching recent books. pub enum RecentBooksError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareRecentBooks { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteRecentBooks { source: rusqlite::Error }, } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a single book. pub enum ScalarBookError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareScalarBook { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteScalarBook { source: rusqlite::Error }, } @@ -75,6 +84,7 @@ pub struct MoreBooksError { } impl Book { + /// Create a book from a database row. fn from_row(row: &Row<'_>) -> Result { Ok(Self { id: row.get(0)?, diff --git a/calibre-db/src/data/series.rs b/calibre-db/src/data/series.rs index 94879b5..d5dc66c 100644 --- a/calibre-db/src/data/series.rs +++ b/calibre-db/src/data/series.rs @@ -24,17 +24,23 @@ pub struct MultiplSeriesError { } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a series' books. pub enum SeriesBooksError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareSeriesBooks { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteSeriesBooks { source: rusqlite::Error }, } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a single series. pub enum ScalarSeriesError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareScalarSeries { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteScalarSeries { source: rusqlite::Error }, } @@ -52,6 +58,7 @@ pub struct MoreSeriesError { } impl Series { + /// Create a series from a database row. fn from_row(row: &Row<'_>) -> Result { Ok(Self { id: row.get(0)?, diff --git a/calibre-db/src/search.rs b/calibre-db/src/search.rs index 01f7d21..93ad429 100644 --- a/calibre-db/src/search.rs +++ b/calibre-db/src/search.rs @@ -35,39 +35,54 @@ const SEARCH_INIT_QUERY: &str = "INSERT INTO search.fts(book_id, data) GROUP BY b.id"; #[derive(Debug, Snafu)] +/// Errors that can occur when ensuring the search database is available. pub enum EnsureSearchDbError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareEnsureSearch { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteEnsureSearch { source: rusqlite::Error }, + /// A failure to attach the database. #[snafu(display("Failed to attach database."))] Attach { source: AttachError }, + /// A failure to initialize the database. #[snafu(display("Failed to initialize database."))] Init { source: InitError }, } #[derive(Debug, Snafu)] +/// Errors that can occur when attaching the search database. pub enum AttachError { + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteAttach { source: rusqlite::Error }, } #[derive(Debug, Snafu)] +/// Errors that can occur when initializing the search database. pub enum InitError { + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareInit { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteInit { source: rusqlite::Error }, } #[derive(Debug, Snafu)] +/// Errors that can occur when searching. pub enum SearchError { + /// A failure to ensure the search database is initialized. #[snafu(display("Failed ensure the search db is initialized."))] EnsureDb { source: EnsureSearchDbError }, + /// A failure to get a connection from the pool. #[snafu(display("Failed to get connection from pool."))] Connection { source: r2d2::Error }, + /// A failure to prepare the SQL statement. #[snafu(display("Failed to prepare statement."))] PrepareSearch { source: rusqlite::Error }, + /// A failure to execute the SQL statement. #[snafu(display("Failed to execute statement."))] ExecuteSearch { source: rusqlite::Error }, } diff --git a/little-hesinde/build.rs b/little-hesinde/build.rs index 0b59d94..8cb51af 100644 --- a/little-hesinde/build.rs +++ b/little-hesinde/build.rs @@ -8,6 +8,7 @@ use std::{ use ignore::Walk; use zip::{CompressionMethod, write::SimpleFileOptions}; +/// Create a zip archive of the source code. fn main() -> Result<(), Box> { let out_dir = env::var("OUT_DIR")?; let src_dir = ".."; diff --git a/little-hesinde/src/api.rs b/little-hesinde/src/api.rs index 7521dc9..93aec22 100644 --- a/little-hesinde/src/api.rs +++ b/little-hesinde/src/api.rs @@ -30,6 +30,7 @@ pub enum SortOrder { } impl From for calibre_db::data::pagination::SortOrder { + /// Convert the API sort order to the database sort order. fn from(val: SortOrder) -> Self { match val { SortOrder::ASC => calibre_db::data::pagination::SortOrder::ASC, diff --git a/little-hesinde/src/api/authors.rs b/little-hesinde/src/api/authors.rs index a03d34e..40c0544 100644 --- a/little-hesinde/src/api/authors.rs +++ b/little-hesinde/src/api/authors.rs @@ -10,13 +10,17 @@ use super::SortOrder; use crate::data::book::Book; #[derive(Debug, Snafu)] +/// Errors that can occur when retrieving a single author. pub enum SingleAuthorError { + /// A failure to fetch author data. #[snafu(display("Failed to fetch author data."))] AuthorData { source: DataStoreError }, + /// A failure to fetch books from the author. #[snafu(display("Failed to fetch books from author."))] BookData { source: DataStoreError }, } +/// Retrieve a single author and all their books. pub async fn single( id: u64, calibre: &Calibre, diff --git a/little-hesinde/src/api/books.rs b/little-hesinde/src/api/books.rs index 44477e4..df7e586 100644 --- a/little-hesinde/src/api/books.rs +++ b/little-hesinde/src/api/books.rs @@ -6,11 +6,14 @@ use snafu::{ResultExt, Snafu}; use crate::data::book::Book; #[derive(Debug, Snafu)] +/// Errors that can occur when fetching recent books. pub enum RecentBooksError { + /// A failure to fetch recent books. #[snafu(display("Failed to fetch recent books."))] RecentBooks { source: DataStoreError }, } +/// Fetch recent books and enrich them with additional information. pub async fn recent(calibre: &Calibre, library_path: &Path) -> Result, RecentBooksError> { let recent_books = calibre.recent_books(25).context(RecentBooksSnafu)?; let recent_books = recent_books diff --git a/little-hesinde/src/api/html.rs b/little-hesinde/src/api/html.rs index db2d9ce..398db5d 100644 --- a/little-hesinde/src/api/html.rs +++ b/little-hesinde/src/api/html.rs @@ -1,3 +1,4 @@ +//! Handlers for HTML responses. pub mod archive; pub mod authors; pub mod books; diff --git a/little-hesinde/src/api/html/archive.rs b/little-hesinde/src/api/html/archive.rs index 46cf1c0..9551fa0 100644 --- a/little-hesinde/src/api/html/archive.rs +++ b/little-hesinde/src/api/html/archive.rs @@ -14,7 +14,9 @@ use crate::{ const SOURCE_ARCHIVE: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/archive.zip")); #[derive(Debug, Snafu)] +/// Errors that can occur when downloading the source code archive. pub enum ArchiveError { + /// A failure to stream the source code archive. #[snafu(display("Failed to stream source code archive."))] Download { source: DownloadError }, } diff --git a/little-hesinde/src/api/html/authors.rs b/little-hesinde/src/api/html/authors.rs index 3797205..604f79c 100644 --- a/little-hesinde/src/api/html/authors.rs +++ b/little-hesinde/src/api/html/authors.rs @@ -21,7 +21,9 @@ use crate::{ }; #[derive(Debug, Snafu)] +/// Errors that can occur when retrieving authors. pub enum RetrieveError { + /// A failure to fetch pagination data. #[snafu(display("Failed to fetch pagination data."))] Authors { source: AuthorError }, } @@ -68,11 +70,14 @@ pub async fn handler( } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching an author. pub enum AuthorError { + /// A failure to fetch pagination data. #[snafu(display("Failed to fetch pagination data."))] Pagination { source: PaginationError }, } +/// Render a paginated list of authors. async fn authors( state: &Arc, cursor: Option<&str>, @@ -89,9 +94,12 @@ async fn authors( } #[derive(Debug, Snafu)] +/// Errors that can occur when retrieving a single author. pub enum SingleError { + /// A failure to fetch author data. #[snafu(display("Failed to fetch author data."))] Data { source: SingleAuthorError }, + /// A failure to render the template. #[snafu(display("Failed to render template."))] Render { source: tera::Error }, } diff --git a/little-hesinde/src/api/html/search.rs b/little-hesinde/src/api/html/search.rs index 8666259..353336d 100644 --- a/little-hesinde/src/api/html/search.rs +++ b/little-hesinde/src/api/html/search.rs @@ -39,6 +39,7 @@ impl HttpStatus for SearchError { http_error!(SearchError); #[derive(Deserialize)] +/// Parameters for a search request. pub struct Params { /// Query for a search request. query: String, diff --git a/little-hesinde/src/api/html/series.rs b/little-hesinde/src/api/html/series.rs index cff3b04..fb87fd4 100644 --- a/little-hesinde/src/api/html/series.rs +++ b/little-hesinde/src/api/html/series.rs @@ -21,7 +21,9 @@ use crate::{ }; #[derive(Debug, Snafu)] +/// Errors that can occur when retrieving series. pub enum RetrieveError { + /// A failure to fetch series data. #[snafu(display("Failed to fetch series data."))] Series { source: SeriesError }, } @@ -68,11 +70,14 @@ pub async fn handler( } #[derive(Debug, Snafu)] +/// Errors that can occur when fetching a series. pub enum SeriesError { + /// A failure to fetch pagination data. #[snafu(display("Failed to fetch pagination data."))] Pagination { source: PaginationError }, } +/// Render a paginated list of series. async fn series( state: &Arc, cursor: Option<&str>, @@ -89,9 +94,12 @@ async fn series( } #[derive(Debug, Snafu)] +/// Errors that can occur when retrieving a single series. pub enum SingleError { + /// A failure to fetch series data. #[snafu(display("Failed to fetch series data."))] Data { source: SingleSeriesError }, + /// A failure to render the template. #[snafu(display("Failed to render template."))] Render { source: tera::Error }, } diff --git a/little-hesinde/src/api/opds.rs b/little-hesinde/src/api/opds.rs index 28e3782..1efe96c 100644 --- a/little-hesinde/src/api/opds.rs +++ b/little-hesinde/src/api/opds.rs @@ -1,3 +1,4 @@ +//! Handlers for OPDS feeds. pub mod authors; pub mod books; pub mod recent; diff --git a/little-hesinde/src/api/opds/authors.rs b/little-hesinde/src/api/opds/authors.rs index e760013..825709f 100644 --- a/little-hesinde/src/api/opds/authors.rs +++ b/little-hesinde/src/api/opds/authors.rs @@ -25,9 +25,12 @@ use crate::{ }; #[derive(Debug, Snafu)] +/// Errors that can occur when retrieving all authors. pub enum AuthorsError { + /// A failure to fetch author data. #[snafu(display("Failed to fetch author data."))] Data { source: DataStoreError }, + /// A failure to render author data. #[snafu(display("Failed to render author data."))] Render { source: AsXmlError }, } @@ -81,9 +84,12 @@ pub async fn handler(State(state): State>) -> Result>) -> Result>) -> Result impl IntoResponse { StaticFile(path) } +/// A wrapper type for static files. pub struct StaticFile(pub T); impl IntoResponse for StaticFile diff --git a/little-hesinde/src/config.rs b/little-hesinde/src/config.rs index 3c46bbc..1b262e4 100644 --- a/little-hesinde/src/config.rs +++ b/little-hesinde/src/config.rs @@ -14,17 +14,22 @@ use crate::cli::Cli; /// Errors from loading application configuration. #[derive(Debug, Snafu)] pub enum LoadError { + /// The provided path is not a calibre library. #[snafu(display("{path} is not a calibre library."))] LibraryPath { path: String }, + /// Could not find the calibre metadata database. #[snafu(display("Could not find calibre metadata at {path}."))] MetadataPath { path: String }, + /// The listening address could not be parsed. #[snafu(display("Invalid listening address {listen_address}."))] ListeningAddressParse { source: io::Error, listen_address: String, }, + /// The listening address is invalid. #[snafu(display("Invalid listening address {listen_address}."))] ListeningAddress { listen_address: String }, + /// The cache directory could not be created. #[snafu(display("Failed to create cach directory at {path}."))] CacheDir { source: io::Error, path: String }, } diff --git a/little-hesinde/src/data.rs b/little-hesinde/src/data.rs index 5bc8fb3..ff9f354 100644 --- a/little-hesinde/src/data.rs +++ b/little-hesinde/src/data.rs @@ -1 +1,2 @@ +//! Data types and functions for enriching calibre data. pub mod book; diff --git a/little-hesinde/src/opds/search.rs b/little-hesinde/src/opds/search.rs index 63f6a10..c533fea 100644 --- a/little-hesinde/src/opds/search.rs +++ b/little-hesinde/src/opds/search.rs @@ -17,8 +17,10 @@ use super::error::{ /// Url pointing to a location. #[derive(Debug, Serialize)] pub struct Url { + /// The media type of the resource. #[serde(rename = "@type")] pub type_name: String, + /// The URL template. #[serde(rename = "@template")] pub template: String, }