bit of documentation

rusty-library/src/handlers/author.rs

@@ -1,3 +1,5 @@
+//! Handle requests for a single author.
+
 use std::sync::Arc;
 
 use calibre_db::data::pagination::SortOrder;
@@ -9,6 +11,7 @@ use poem::{
 
 use crate::{app_state::AppState, data::book::Book, handlers::error::HandlerError, Accept};
 
+/// Handle a request for an author with `id` and decide whether to render to html or OPDS.
 #[handler]
 pub async fn handler(
     id: Path<u64>,

rusty-library/src/handlers/authors.rs

@@ -1,3 +1,5 @@
+//! Handle requests for multiple authors.
+
 use std::sync::Arc;
 
 use calibre_db::{calibre::Calibre, data::pagination::SortOrder};
@@ -9,6 +11,7 @@ use poem::{
 
 use crate::{app_state::AppState, Accept};
 
+/// Handle a request for multiple authors, starting at the first.
 #[handler]
 pub async fn handler_init(
     accept: Data<&Accept>,
@@ -17,6 +20,8 @@ pub async fn handler_init(
     authors(&accept, &state.calibre, None, &SortOrder::ASC).await
 }
 
+/// Handle a request for multiple authors, starting at the `cursor` and going in the direction of
+/// `sort_order`.
 #[handler]
 pub async fn handler(
     Path((cursor, sort_order)): Path<(String, SortOrder)>,

rusty-library/src/handlers/books.rs

@@ -1,3 +1,5 @@
+//! Handle requests for multiple books.
+
 use std::sync::Arc;
 
 use calibre_db::data::pagination::SortOrder;
@@ -9,6 +11,7 @@ use poem::{
 
 use crate::{app_state::AppState, Accept};
 
+/// Handle a request for multiple books, starting at the first.
 #[handler]
 pub async fn handler_init(
     accept: Data<&Accept>,
@@ -17,6 +20,8 @@ pub async fn handler_init(
     books(&accept, &state, None, &SortOrder::ASC).await
 }
 
+/// Handle a request for multiple books, starting at the `cursor` and going in the direction of
+/// `sort_order`.
 #[handler]
 pub async fn handler(
     Path((cursor, sort_order)): Path<(String, SortOrder)>,

rusty-library/src/handlers/cover.rs

@@ -1,3 +1,5 @@
+//! Handle requests for cover images.
+
 use std::{fs::File, io::Read, sync::Arc};
 
 use poem::{
@@ -9,6 +11,7 @@ use poem::{
 
 use crate::{app_state::AppState, handlers::error::HandlerError};
 
+/// Handle a request for the cover image of book with id `id`.
 #[handler]
 pub async fn handler(
     id: Path<u64>,

rusty-library/src/handlers/download.rs

@@ -1,3 +1,5 @@
+//! Handle requests for specific formats of a book.
+
 use std::{fs::File, io::Read, sync::Arc};
 
 use poem::{
@@ -13,6 +15,7 @@ use crate::{
     handlers::error::HandlerError,
 };
 
+/// Handle a request for a book with id `id` in format `format`.
 #[handler]
 pub async fn handler(
     Path((id, format)): Path<(u64, String)>,
@@ -25,7 +28,11 @@ pub async fn handler(
     let book = Book::full_book(&book, &state).ok_or(NotFoundError)?;
     let format = Format(format);
     let file_name = book.formats.get(&format).ok_or(NotFoundError)?;
-    let file_path = state.config.library_path.join(book.path).join(file_name);
+    let file_path = state
+        .config
+        .library_path
+        .join(book.data.path)
+        .join(file_name);
     let mut file = File::open(file_path).map_err(|_| NotFoundError)?;
 
     let mut data = Vec::new();

rusty-library/src/handlers/error.rs

@@ -1,3 +1,5 @@
+//! Error handling for requests handlers.
+
 use calibre_db::data::error::DataStoreError;
 use poem::{error::ResponseError, http::StatusCode, Body, Response};
 use thiserror::Error;
@@ -6,15 +8,22 @@ use uuid::Uuid;
 
 use crate::opds::error::OpdsError;
 
+/// Errors happening during handling of requests.
 #[derive(Error, Debug)]
 #[error("opds error")]
 pub enum HandlerError {
+    /// Error rendering OPDS.
     #[error("opds error")]
     OpdsError(#[from] OpdsError),
+    /// Error fetching data from calibre.
     #[error("data error")]
     DataError(#[from] DataStoreError),
 }
 
+/// Convert a [`HandlerError`](enum@HandlerError) into a suitable response error.
+///
+/// Log the real error (internal) with an uuid and send a suitable error message to the user with
+/// the same uuid (for correlation purposes).
 impl ResponseError for HandlerError {
     fn status(&self) -> StatusCode {
         match &self {

rusty-library/src/handlers/html/author.rs

@@ -1,9 +1,12 @@
+//! Handle a single author for html.
+
 use calibre_db::data::author::Author;
 use poem::{error::InternalServerError, web::Html, IntoResponse, Response};
 use tera::Context;
 
 use crate::{data::book::Book, templates::TEMPLATES};
 
+/// Render a single author in html.
 pub async fn handler(author: Author, books: Vec<Book>) -> Result<Response, poem::Error> {
     let mut context = Context::new();
     context.insert("title", &author.name);

rusty-library/src/handlers/html/authors.rs

@@ -1,8 +1,11 @@
+//! Handle multiple authors in html.
+
 use calibre_db::{calibre::Calibre, data::pagination::SortOrder};
 use poem::Response;
 
 use crate::handlers::paginated;
 
+/// Render all authors paginated by cursor in html.
 pub async fn handler(
     calibre: &Calibre,
     cursor: Option<&str>,

rusty-library/src/handlers/html/books.rs

@@ -1,8 +1,11 @@
+//! Handle multiple books in html.
+
 use calibre_db::data::pagination::SortOrder;
 use poem::Response;
 
 use crate::{app_state::AppState, data::book::Book, handlers::paginated};
 
+/// Render all books paginated by cursor in html.
 pub async fn handler(
     state: &AppState,
     cursor: Option<&str>,
@@ -16,7 +19,7 @@ pub async fn handler(
                 .books(25, cursor, sort_order)
                 .map(|x| x.iter().filter_map(|y| Book::full_book(y, state)).collect())
         },
-        |book| book.sort.clone(),
+        |book| book.data.sort.clone(),
         |cursor| state.calibre.has_previous_books(cursor),
         |cursor| state.calibre.has_more_books(cursor),
     )

rusty-library/src/handlers/html/recent.rs

@@ -1,8 +1,11 @@
+//! Handle recent books in html.
+
 use poem::{error::InternalServerError, web::Html, IntoResponse, Response};
 use tera::Context;
 
 use crate::{data::book::Book, templates::TEMPLATES};
 
+/// Render recent books as html.
 pub async fn handler(recent_books: Vec<Book>) -> Result<Response, poem::Error> {
     let mut context = Context::new();
     context.insert("title", "Recent Books");

rusty-library/src/handlers/html/series.rs

@@ -1,8 +1,11 @@
+//! Handle multiple series in html.
+
 use calibre_db::{calibre::Calibre, data::pagination::SortOrder};
 use poem::Response;
 
 use crate::handlers::paginated;
 
+/// Render all series paginated by cursor as html.
 pub async fn handler(
     calibre: &Calibre,
     cursor: Option<&str>,

rusty-library/src/handlers/html/series_single.rs

@@ -1,9 +1,12 @@
+//! Handle a single series in html.
+
 use calibre_db::data::series::Series;
 use poem::{error::InternalServerError, web::Html, IntoResponse, Response};
 use tera::Context;
 
 use crate::{data::book::Book, templates::TEMPLATES};
 
+/// Render a single series as html.
 pub async fn handler(series: Series, books: Vec<Book>) -> Result<Response, poem::Error> {
     let mut context = Context::new();
     context.insert("title", &series.name);

rusty-library/src/handlers/opds/author.rs

@@ -1,3 +1,5 @@
+//! Handle a single author for opds.
+
 use calibre_db::data::author::Author;
 use poem::{IntoResponse, Response};
 use time::OffsetDateTime;
@@ -8,6 +10,7 @@ use crate::{
     opds::{entry::Entry, feed::Feed, link::Link, media_type::MediaType, relation::Relation},
 };
 
+/// Render a single author as an OPDS entry embedded in a feed.
 pub async fn handler(author: Author, books: Vec<Book>) -> Result<Response, poem::Error> {
     let entries: Vec<Entry> = books.into_iter().map(Entry::from).collect();
     let now = OffsetDateTime::now_utc();

rusty-library/src/handlers/opds/authors.rs

@@ -1,3 +1,5 @@
+//! Handle multiple authors for opds.
+
 use calibre_db::{
     calibre::Calibre,
     data::{author::Author as DbAuthor, pagination::SortOrder},
@@ -10,6 +12,7 @@ use crate::{
     opds::{entry::Entry, feed::Feed, link::Link, media_type::MediaType, relation::Relation},
 };
 
+/// Render all authors as OPDS entries embedded in a feed.
 pub async fn handler(
     calibre: &Calibre,
     _cursor: Option<&str>,

rusty-library/src/handlers/opds/books.rs

@@ -1,3 +1,5 @@
+//! Handle multiple books for opds.
+
 use calibre_db::data::pagination::SortOrder;
 use poem::{IntoResponse, Response};
 use time::OffsetDateTime;
@@ -9,6 +11,7 @@ use crate::{
     opds::{entry::Entry, feed::Feed, link::Link, media_type::MediaType, relation::Relation},
 };
 
+/// Render all books as OPDS entries embedded in a feed.
 pub async fn handler(
     state: &AppState,
     _cursor: Option<&str>,

rusty-library/src/handlers/opds/feed.rs

@@ -1,3 +1,5 @@
+//! Handle the OPDS root feed.
+
 use poem::{handler, web::WithContentType, IntoResponse};
 use time::OffsetDateTime;
 
@@ -9,6 +11,7 @@ use crate::{
     },
 };
 
+/// Render a root OPDS feed with links to the subsections (authors, books, series and recent).
 #[handler]
 pub async fn handler() -> Result<WithContentType<String>, poem::Error> {
     let now = OffsetDateTime::now_utc();

rusty-library/src/handlers/opds/recent.rs

@@ -1,3 +1,5 @@
+//! Handle recent books for OPDS.
+
 use poem::{IntoResponse, Response};
 use time::OffsetDateTime;
 
@@ -7,6 +9,7 @@ use crate::{
     opds::{entry::Entry, feed::Feed, link::Link, media_type::MediaType, relation::Relation},
 };
 
+/// Render recent books as OPDS entries embedded in a feed.
 pub async fn handler(recent_books: Vec<Book>) -> Result<Response, poem::Error> {
     let entries: Vec<Entry> = recent_books.into_iter().map(Entry::from).collect();
     let now = OffsetDateTime::now_utc();

rusty-library/src/handlers/opds/series.rs

@@ -1,3 +1,5 @@
+//! Handle multiple series for OPDS.
+
 use calibre_db::{calibre::Calibre, data::pagination::SortOrder};
 use poem::{IntoResponse, Response};
 use time::OffsetDateTime;
@@ -7,6 +9,7 @@ use crate::{
     opds::{entry::Entry, feed::Feed, link::Link, media_type::MediaType, relation::Relation},
 };
 
+/// Render all series as OPDS entries embedded in a feed.
 pub async fn handler(
     calibre: &Calibre,
     _cursor: Option<&str>,

rusty-library/src/handlers/opds/series_single.rs

@@ -1,3 +1,5 @@
+//! Handle a single series for opds.
+
 use calibre_db::data::series::Series;
 use poem::{IntoResponse, Response};
 use time::OffsetDateTime;
@@ -8,6 +10,7 @@ use crate::{
     opds::{entry::Entry, feed::Feed, link::Link, media_type::MediaType, relation::Relation},
 };
 
+/// Render a single series as an OPDS entry embedded in a feed.
 pub async fn handler(series: Series, books: Vec<Book>) -> Result<Response, poem::Error> {
     let entries: Vec<Entry> = books.into_iter().map(Entry::from).collect();
     let now = OffsetDateTime::now_utc();

rusty-library/src/handlers/paginated.rs

@@ -1,3 +1,5 @@
+//! Deal with cursor pagination.
+
 use std::fmt::Debug;
 
 use calibre_db::data::error::DataStoreError;
@@ -9,6 +11,7 @@ use crate::templates::TEMPLATES;
 
 use super::error::HandlerError;
 
+/// Render a tera template with paginated items and generate back and forth links.
 pub fn render<T: Serialize + Debug, F, S, P, M>(
     template: &str,
     fetcher: F,

rusty-library/src/handlers/recent.rs

@@ -1,9 +1,12 @@
+//! Handle requests for recent books.
+
 use std::sync::Arc;
 
 use poem::{handler, web::Data, Response};
 
 use crate::{app_state::AppState, data::book::Book, handlers::error::HandlerError, Accept};
 
+/// Handle a request recent books and decide whether to render to html or OPDS.
 #[handler]
 pub async fn handler(
     accept: Data<&Accept>,

rusty-library/src/handlers/series.rs

@@ -1,3 +1,5 @@
+//! Handle requests for multiple series.
+
 use std::sync::Arc;
 
 use calibre_db::data::pagination::SortOrder;
@@ -9,6 +11,7 @@ use poem::{
 
 use crate::{app_state::AppState, Accept};
 
+/// Handle a request for multiple series, starting at the first.
 #[handler]
 pub async fn handler_init(
     accept: Data<&Accept>,
@@ -17,6 +20,8 @@ pub async fn handler_init(
     series(&accept, &state, None, &SortOrder::ASC).await
 }
 
+/// Handle a request for multiple series, starting at the `cursor` and going in the direction of
+/// `sort_order`.
 #[handler]
 pub async fn handler(
     Path((cursor, sort_order)): Path<(String, SortOrder)>,

rusty-library/src/handlers/series_single.rs

@@ -1,3 +1,5 @@
+//! Handle requests for a single series.
+
 use std::sync::Arc;
 
 use poem::{
@@ -8,6 +10,7 @@ use poem::{
 
 use crate::{app_state::AppState, data::book::Book, handlers::error::HandlerError, Accept};
 
+/// Handle a request for a series with `id` and decide whether to render to html or OPDS.
 #[handler]
 pub async fn handler(
     id: Path<u64>,