From f9971fe6ff833d0badde9b8786543e62a3783aed Mon Sep 17 00:00:00 2001
From: Wojciech Kozlowski <wk@wojciechkozlowski.eu>
Date: Fri, 12 Jan 2024 21:49:26 +0100
Subject: [PATCH] Add docstrings

---
 src/lib.rs                    | 15 ++++++++++++++-
 src/library/beets/executor.rs |  2 ++
 src/library/mod.rs            |  2 +-
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index bbbae7f..535fa40 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -29,6 +29,7 @@ pub trait IMbid {
     fn mbid(&self) -> &str;
 }
 
+/// The different URL types supported by MusicHoard.
 #[derive(Debug)]
 enum UrlType {
     MusicBrainz,
@@ -37,6 +38,7 @@ enum UrlType {
     Qobuz,
 }
 
+/// Invalid URL error.
 struct InvalidUrlError {
     url_type: UrlType,
     url: String,
@@ -53,6 +55,7 @@ impl Display for InvalidUrlError {
 pub struct MusicBrainz(Url);
 
 impl MusicBrainz {
+    /// Validate and wrap a MusicBrainz URL.
     pub fn new<S: AsRef<str>>(url: S) -> Result<Self, Error> {
         let url = Url::parse(url.as_ref())?;
 
@@ -112,6 +115,7 @@ impl IMbid for MusicBrainz {
 pub struct MusicButler(Url);
 
 impl MusicButler {
+    /// Validate and wrap a MusicButler URL.
     pub fn new<S: AsRef<str>>(url: S) -> Result<Self, Error> {
         let url = Url::parse(url.as_ref())?;
 
@@ -157,6 +161,7 @@ impl IUrl for MusicButler {
 pub struct Bandcamp(Url);
 
 impl Bandcamp {
+    /// Validate and wrap a Bandcamp URL.
     pub fn new<S: AsRef<str>>(url: S) -> Result<Self, Error> {
         let url = Url::parse(url.as_ref())?;
 
@@ -202,6 +207,7 @@ impl IUrl for Bandcamp {
 pub struct Qobuz(Url);
 
 impl Qobuz {
+    /// Validate and wrap a Qobuz URL.
     pub fn new<S: AsRef<str>>(url: S) -> Result<Self, Error> {
         let url = Url::parse(url.as_ref())?;
 
@@ -423,6 +429,7 @@ macro_rules! artist_multi_url_dispatch {
 }
 
 impl Artist {
+    /// Create new [`Artist`] with the given [`ArtistId`].
     pub fn new<ID: Into<ArtistId>>(id: ID) -> Self {
         Artist {
             id: id.into(),
@@ -698,8 +705,10 @@ pub struct MusicHoard<LIB, DB> {
     database: DB,
 }
 
-// Unit structs to ensure library/database are not compiled in.
+/// Phantom type for when a library implementation is not needed.
 pub struct NoLibrary;
+
+/// Phantom type for when a database implementation is not needed.
 pub struct NoDatabase;
 
 macro_rules! music_hoard_unique_url_dispatch {
@@ -787,6 +796,7 @@ impl<LIB, DB> MusicHoard<LIB, DB> {
         }
     }
 
+    /// Retrieve the [`Collection`].
     pub fn get_collection(&self) -> &Collection {
         &self.collection
     }
@@ -914,6 +924,7 @@ impl<LIB, DB> MusicHoard<LIB, DB> {
 }
 
 impl<LIB: ILibrary, DB> MusicHoard<LIB, DB> {
+    /// Rescan the library and merge with the in-memory collection.
     pub fn rescan_library(&mut self) -> Result<(), Error> {
         let items = self.library.list(&Query::new())?;
         let mut library_collection = Self::items_to_artists(items);
@@ -927,6 +938,7 @@ impl<LIB: ILibrary, DB> MusicHoard<LIB, DB> {
 }
 
 impl<LIB, DB: IDatabase> MusicHoard<LIB, DB> {
+    /// Load the database and merge with the in-memory collection.
     pub fn load_from_database(&mut self) -> Result<(), Error> {
         let mut database_collection = self.database.load()?;
         Self::sort(&mut database_collection);
@@ -937,6 +949,7 @@ impl<LIB, DB: IDatabase> MusicHoard<LIB, DB> {
         Ok(())
     }
 
+    /// Save the in-memory collection to the database.
     pub fn save_to_database(&mut self) -> Result<(), Error> {
         self.database.save(&self.collection)?;
         Ok(())
diff --git a/src/library/beets/executor.rs b/src/library/beets/executor.rs
index 50fa943..1c7e34f 100644
--- a/src/library/beets/executor.rs
+++ b/src/library/beets/executor.rs
@@ -76,6 +76,8 @@ impl IBeetsLibraryExecutorPrivate for BeetsLibraryProcessExecutor {}
 // GRCOV_EXCL_START
 #[cfg(feature = "ssh-library")]
 pub mod ssh {
+    //! Module for interacting with the music library via
+    //! [beets](https://beets.readthedocs.io/en/stable/) over SSH.
 
     use openssh::{KnownHosts, Session};
     use tokio::runtime::{self, Runtime};
diff --git a/src/library/mod.rs b/src/library/mod.rs
index cea936e..bc476ed 100644
--- a/src/library/mod.rs
+++ b/src/library/mod.rs
@@ -13,7 +13,7 @@ pub mod beets;
 /// Trait for interacting with the music library.
 #[cfg_attr(test, automock)]
 pub trait ILibrary {
-    /// List lirbary items that match the a specific query.
+    /// List library items that match the a specific query.
     fn list(&mut self, query: &Query) -> Result<Vec<Item>, Error>;
 }
 
-- 
2.45.2