From e6fa8a0eeb95fe84a88a4444598c0be7780e1e0f Mon Sep 17 00:00:00 2001
From: Chewing_Bever <roosensjef@gmail.com>
Date: Tue, 4 Jul 2023 15:49:16 +0200
Subject: [PATCH] docs: add a few docstrings

---
 src/backup/manager/mod.rs |  3 ++-
 src/backup/mod.rs         | 22 +++++++++++++++++++++-
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/backup/manager/mod.rs b/src/backup/manager/mod.rs
index 7969021..72743b7 100644
--- a/src/backup/manager/mod.rs
+++ b/src/backup/manager/mod.rs
@@ -53,7 +53,8 @@ where
         }
     }
 
-    /// Create a new backup with the expected type.
+    /// Create a new backup, either full or incremental, depending on the state of the current
+    /// chain.
     pub fn create_backup(&mut self) -> io::Result<()> {
         // We start a new chain if the current chain is complete, or if there isn't a first chain
         // yet
diff --git a/src/backup/mod.rs b/src/backup/mod.rs
index ea7f2f9..a4081f9 100644
--- a/src/backup/mod.rs
+++ b/src/backup/mod.rs
@@ -56,6 +56,7 @@ impl Backup<()> {
 }
 
 impl<T: Clone> Backup<T> {
+    /// Set the backup's metadata.
     pub fn set_metadata(&mut self, metadata: T) {
         self.metadata = Some(metadata);
     }
@@ -126,7 +127,19 @@ impl<T: Clone> Backup<T> {
         })
     }
 
-    /// Create a new incremental backup from a given previous backup
+    /// Create a new Incremental backup from the given state, populated with the given directories.
+    ///
+    /// # Arguments
+    ///
+    /// * `previous_state` - State the file system was in during the previous backup in the chain
+    /// * `previous_start_time` - Start time of the previous backup; used to filter files
+    /// * `backup_dir` - Directory to store archive in
+    /// * `dirs` - list of tuples `(path_in_tar, src_dir)` with `path_in_tar` the directory name
+    ///     under which `src_dir`'s contents should be stored in the archive
+    ///
+    /// # Returns
+    ///
+    /// The `Backup` instance describing this new backup.
     pub fn create_from<P: AsRef<Path>>(
         previous_state: HashMap<PathBuf, HashSet<PathBuf>>,
         previous_start_time: chrono::DateTime<Utc>,
@@ -184,6 +197,13 @@ impl<T: Clone> Backup<T> {
         })
     }
 
+    /// Restore the backup by extracting its contents to the respective directories.
+    ///
+    /// # Arguments
+    ///
+    /// * `backup_dir` - Backup directory where the file is stored
+    /// * `dirs` - list of tuples `(path_in_tar, dst_dir)` with `dst_dir` the directory on-disk
+    ///     where the files stored under `path_in_tar` inside the tarball should be extracted to.
     pub fn restore<P: AsRef<Path>>(
         &self,
         backup_dir: P,