bit of documentation

calibre-db/src/data/book.rs

@@ -1,3 +1,5 @@
+//! Book data.
+
 use rusqlite::{named_params, Connection, Row};
 use serde::Serialize;
 use time::OffsetDateTime;
@@ -7,14 +9,22 @@ use super::{
     pagination::{Pagination, SortOrder},
 };
 
-#[derive(Debug, Serialize)]
+/// Book in calibre.
+#[derive(Debug, Clone, Serialize)]
 pub struct Book {
+    /// Id in database.
     pub id: u64,
+    /// Book title.
     pub title: String,
+    /// Book title for sorting.
     pub sort: String,
+    /// Folder of the book within the calibre library.
     pub path: String,
+    /// Uuid of the book.
     pub uuid: String,
+    /// When was the book last modified.
     pub last_modified: OffsetDateTime,
+    /// Optional description.
     pub description: Option<String>,
 }
 
@@ -31,6 +41,8 @@ impl Book {
         })
     }
 
+    /// Fetch book data from calibre, starting at `cursor`, fetching up to an amount of `limit` and
+    /// ordering by `sort_order`.
     pub fn multiple(
         conn: &Connection,
         limit: u64,
@@ -47,6 +59,8 @@ impl Book {
         )
     }
 
+    /// Fetch books for an author specified by `author_id`, paginate the books by starting at `cursor`,
+    /// fetching up to an amount of `limit` and ordering by `sort_order`.
     pub fn author_books(
         conn: &Connection,
         author_id: u64,
@@ -66,6 +80,7 @@ impl Book {
         )
     }
 
+    /// Get all books belonging to the series with id `id`.
     pub fn series_books(conn: &Connection, id: u64) -> Result<Vec<Book>, DataStoreError> {
         let mut stmt = conn.prepare(
             "SELECT books.id, books.title, books.sort, books.path, books.uuid, books.last_modified, comments.text FROM series \
@@ -80,6 +95,7 @@ impl Book {
         Ok(iter.filter_map(Result::ok).collect())
     }
 
+    /// Get recent books up to a limit of `limit`.
     pub fn recents(conn: &Connection, limit: u64) -> Result<Vec<Self>, DataStoreError> {
         let mut stmt = conn.prepare(
             "SELECT books.id, books.title, books.sort, books.path, books.uuid, books.last_modified, comments.text \
@@ -90,6 +106,7 @@ impl Book {
         Ok(iter.filter_map(Result::ok).collect())
     }
 
+    /// Get a single book, specified `id`.
     pub fn scalar_book(conn: &Connection, id: u64) -> Result<Self, DataStoreError> {
         let mut stmt = conn.prepare(
             "SELECT books.id, books.title, books.sort, books.path, books.uuid, books.last_modified, comments.text \
@@ -99,10 +116,12 @@ impl Book {
         Ok(stmt.query_row(params, Self::from_row)?)
     }
 
+    /// Check if there are more books before the specified cursor.
     pub fn has_previous_books(conn: &Connection, sort_title: &str) -> Result<bool, DataStoreError> {
         Pagination::has_prev_or_more(conn, "books", sort_title, &SortOrder::DESC)
     }
 
+    /// Check if there are more books after the specified cursor.
     pub fn has_more_books(conn: &Connection, sort_title: &str) -> Result<bool, DataStoreError> {
         Pagination::has_prev_or_more(conn, "books", sort_title, &SortOrder::ASC)
     }