chore(docs): update library documentation

Signed-off-by: simonsan <[email protected]>

src/commands.rs

@@ -215,10 +215,13 @@ fn open_repository(config: &Arc<RusticConfig>) -> Result<Repository<ProgressOpti
     Err(anyhow!("incorrect password"))
 }
 
-#[test]
-fn verify_cli() {
+#[cfg(test)]
+mod tests {
     use crate::commands::EntryPoint;
     use clap::CommandFactory;
 
-    EntryPoint::command().debug_assert();
+    #[test]
+    fn verify_cli() {
+        EntryPoint::command().debug_assert();
+    }
 }

src/commands/backup.rs

@@ -2,8 +2,6 @@
 
 use std::path::PathBuf;
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{
     commands::open_repository,
     helpers::bytes_size_to_string,
@@ -49,6 +47,7 @@ pub struct BackupCmd {
     #[clap(long, value_name = "PATH")]
     as_path: Option<PathBuf>,
 
+    /// Ignore save options
     #[clap(flatten)]
     #[serde(flatten)]
     ignore_save_opts: LocalSourceSaveOptions,
@@ -63,28 +62,34 @@ pub struct BackupCmd {
     #[merge(strategy = merge::bool::overwrite_false)]
     init: bool,
 
+    /// Parent processing options
     #[clap(flatten, next_help_heading = "Options for parent processing")]
     #[serde(flatten)]
     parent_opts: ParentOptions,
 
+    /// Exclude options
     #[clap(flatten, next_help_heading = "Exclude options")]
     #[serde(flatten)]
     ignore_filter_opts: LocalSourceFilterOptions,
 
+    /// Snapshot options
     #[clap(flatten, next_help_heading = "Snapshot options")]
     #[serde(flatten)]
     snap_opts: SnapshotOptions,
 
+    /// Key options (when using --init)
     #[clap(flatten, next_help_heading = "Key options (when using --init)")]
     #[serde(skip)]
     #[merge(skip)]
     key_opts: KeyOptions,
 
+    /// Config options (when using --init)
     #[clap(flatten, next_help_heading = "Config options (when using --init)")]
     #[serde(skip)]
     #[merge(skip)]
     config_opts: ConfigOptions,
 
+    /// Backup sources
     #[clap(skip)]
     #[merge(strategy = merge_sources)]
     sources: Vec<BackupCmd>,
@@ -95,7 +100,13 @@ pub struct BackupCmd {
     source: String,
 }
 
-// Merge backup sources: If a source is already defined on left, use that. Else add it.
+/// Merge backup sources
+///
+/// If a source is already defined on left, use that. Else add it.
+///
+/// # Arguments
+///
+/// * `left` - Vector of backup sources
 pub(crate) fn merge_sources(left: &mut Vec<BackupCmd>, mut right: Vec<BackupCmd>) {
     left.append(&mut right);
     left.sort_by(|opt1, opt2| opt1.source.cmp(&opt2.source));

src/commands/cat.rs

@@ -1,7 +1,5 @@
 //! `cat` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{commands::open_repository, status_err, Application, RUSTIC_APP};
 
 use abscissa_core::{Command, Runnable, Shutdown};
@@ -11,12 +9,15 @@ use anyhow::Result;
 use rustic_core::repofile::{BlobType, FileType};
 
 /// `cat` subcommand
+///
+/// Output the contents of a file or blob
 #[derive(clap::Parser, Command, Debug)]
 pub(crate) struct CatCmd {
     #[clap(subcommand)]
     cmd: CatSubCmd,
 }
 
+/// `cat` subcommands
 #[derive(clap::Subcommand, Debug)]
 enum CatSubCmd {
     /// Display a tree blob

src/commands/check.rs

@@ -1,7 +1,5 @@
 //! `check` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{commands::open_repository, status_err, Application, RUSTIC_APP};
 
 use abscissa_core::{Command, Runnable, Shutdown};
@@ -11,6 +9,7 @@ use rustic_core::CheckOptions;
 /// `check` subcommand
 #[derive(clap::Parser, Command, Debug)]
 pub(crate) struct CheckCmd {
+    /// Check options
     #[clap(flatten)]
     opts: CheckOptions,
 }

src/commands/completions.rs

@@ -1,7 +1,5 @@
 //! `completions` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use abscissa_core::{Command, Runnable};
 
 use std::io::Write;

src/commands/config.rs

@@ -1,7 +1,5 @@
 //! `config` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{commands::open_repository, status_err, Application, RUSTIC_APP};
 
 use abscissa_core::{Command, Runnable, Shutdown};
@@ -13,6 +11,7 @@ use rustic_core::ConfigOptions;
 /// `config` subcommand
 #[derive(clap::Parser, Command, Debug)]
 pub(crate) struct ConfigCmd {
+    /// Config options
     #[clap(flatten)]
     config_opts: ConfigOptions,
 }

src/commands/copy.rs

@@ -1,7 +1,5 @@
 //! `copy` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{
     commands::open_repository, helpers::table_with_titles, status_err, Application, RUSTIC_APP,
 };
@@ -25,12 +23,15 @@ pub(crate) struct CopyCmd {
     #[clap(long)]
     init: bool,
 
+    /// Key options (when using --init)
     #[clap(flatten, next_help_heading = "Key options (when using --init)")]
     key_opts: KeyOptions,
 }
 
+/// Target repository options
 #[derive(Default, Clone, Debug, Deserialize, Merge)]
 pub struct Targets {
+    /// Target repositories
     #[merge(strategy = merge::vec::overwrite_empty)]
     targets: Vec<RepositoryOptions>,
 }

src/commands/diff.rs

@@ -1,7 +1,5 @@
 //! `diff` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{commands::open_repository, status_err, Application, RUSTIC_APP};
 
 use abscissa_core::{Command, Runnable, Shutdown};
@@ -35,6 +33,7 @@ pub(crate) struct DiffCmd {
     #[clap(long)]
     no_content: bool,
 
+    /// Ignore options
     #[clap(flatten)]
     ignore_opts: LocalSourceFilterOptions,
 }
@@ -122,6 +121,16 @@ impl DiffCmd {
     }
 }
 
+/// Split argument into snapshot id and path
+///
+/// # Arguments
+///
+/// * `arg` - argument to split
+/// * `default_path` - default path if no path is given
+///
+/// # Returns
+///
+/// A tuple of the snapshot id and the path
 fn arg_to_snap_path<'a>(arg: &'a str, default_path: &'a str) -> (Option<&'a str>, &'a str) {
     match arg.split_once(':') {
         Some((id, path)) => (Some(id), path),
@@ -135,6 +144,25 @@ fn arg_to_snap_path<'a>(arg: &'a str, default_path: &'a str) -> (Option<&'a str>
     }
 }
 
+/// Check if the content of a file in a snapshot is identical to the content of a local file
+///
+/// # Arguments
+///
+/// * `local` - local destination
+/// * `repo` - repository
+/// * `path` - path of the file in the snapshot
+/// * `node` - node of the file in the snapshot
+///
+/// # Errors
+///
+/// * [`RepositoryErrorKind::IdNotFound`] - If the id of a blob is not found in the repository
+///
+/// # Returns
+///
+/// `true` if the content of the file in the snapshot is identical to the content of the local file,
+/// `false` otherwise
+///
+/// [`RepositoryErrorKind::IdNotFound`]: rustic_core::error::RepositoryErrorKind::IdNotFound
 fn identical_content_local<P, S: IndexedFull>(
     local: &LocalDestination,
     repo: &Repository<P, S>,
@@ -155,6 +183,19 @@ fn identical_content_local<P, S: IndexedFull>(
     Ok(true)
 }
 
+/// Compare two streams of nodes and print the differences
+///
+/// # Arguments
+///
+/// * `tree_streamer1` - first stream of nodes
+/// * `tree_streamer2` - second stream of nodes
+/// * `no_content` - don't check for different file contents
+/// * `file_identical` - function to check if the content of two files is identical
+/// * `metadata` - show differences in metadata
+///
+/// # Errors
+///
+// TODO!: add errors!
 fn diff(
     mut tree_streamer1: impl Iterator<Item = RusticResult<(PathBuf, Node)>>,
     mut tree_streamer2: impl Iterator<Item = RusticResult<(PathBuf, Node)>>,

src/commands/dump.rs

@@ -1,7 +1,5 @@
 //! `dump` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{commands::open_repository, status_err, Application, RUSTIC_APP};
 
 use abscissa_core::{Command, Runnable, Shutdown};

src/commands/forget.rs

@@ -1,7 +1,5 @@
 //! `forget` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{
     commands::open_repository, helpers::table_with_titles, status_err, Application, RusticConfig,
     RUSTIC_APP,
@@ -32,9 +30,11 @@ pub(super) struct ForgetCmd {
     #[clap(long)]
     json: bool,
 
+    /// Forget options
     #[clap(flatten)]
     config: ForgetOptions,
 
+    /// Prune options (only when used with --prune)
     #[clap(
         flatten,
         next_help_heading = "PRUNE OPTIONS (only when used with --prune)"
@@ -57,6 +57,7 @@ impl Override<RusticConfig> for ForgetCmd {
     }
 }
 
+/// Forget options
 #[serde_as]
 #[derive(Clone, Default, Debug, clap::Parser, Deserialize, Merge)]
 #[serde(default, rename_all = "kebab-case")]
@@ -71,10 +72,12 @@ pub struct ForgetOptions {
     #[merge(strategy = merge::bool::overwrite_false)]
     prune: bool,
 
+    /// Snapshot filter options
     #[clap(flatten, next_help_heading = "Snapshot filter options")]
     #[serde(flatten)]
     filter: SnapshotFilter,
 
+    /// Retention options
     #[clap(flatten, next_help_heading = "Retention options")]
     #[serde(flatten)]
     keep: KeepOptions,
@@ -146,6 +149,11 @@ impl ForgetCmd {
     }
 }
 
+/// Print groups to stdout
+///
+/// # Arguments
+///
+/// * `groups` - forget groups to print
 fn print_groups(groups: &ForgetGroups) {
     for ForgetGroup { group, snapshots } in &groups.0 {
         if !group.is_empty() {

src/commands/init.rs

@@ -1,7 +1,5 @@
 //! `init` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use abscissa_core::{status_err, Command, Runnable, Shutdown};
 use anyhow::{bail, Result};
 
@@ -14,9 +12,11 @@ use rustic_core::{ConfigOptions, KeyOptions, OpenStatus, Repository};
 /// `init` subcommand
 #[derive(clap::Parser, Command, Debug)]
 pub(crate) struct InitCmd {
+    /// Key options
     #[clap(flatten, next_help_heading = "Key options")]
     key_opts: KeyOptions,
 
+    /// Config options
     #[clap(flatten, next_help_heading = "Config options")]
     config_opts: ConfigOptions,
 }
@@ -48,6 +48,31 @@ impl InitCmd {
     }
 }
 
+/// Initialize repository
+///
+/// # Arguments
+///
+/// * `repo` - Repository to initialize
+/// * `key_opts` - Key options
+/// * `config_opts` - Config options
+///
+/// # Errors
+///
+///  * [`RepositoryErrorKind::OpeningPasswordFileFailed`] - If opening the password file failed
+/// * [`RepositoryErrorKind::ReadingPasswordFromReaderFailed`] - If reading the password failed
+/// * [`RepositoryErrorKind::FromSplitError`] - If splitting the password command failed
+/// * [`RepositoryErrorKind::PasswordCommandParsingFailed`] - If parsing the password command failed
+/// * [`RepositoryErrorKind::ReadingPasswordFromCommandFailed`] - If reading the password from the command failed
+///
+/// # Returns
+///
+/// Returns the initialized repository
+///
+/// [`RepositoryErrorKind::OpeningPasswordFileFailed`]: rustic_core::error::RepositoryErrorKind::OpeningPasswordFileFailed
+/// [`RepositoryErrorKind::ReadingPasswordFromReaderFailed`]: rustic_core::error::RepositoryErrorKind::ReadingPasswordFromReaderFailed
+/// [`RepositoryErrorKind::FromSplitError`]: rustic_core::error::RepositoryErrorKind::FromSplitError
+/// [`RepositoryErrorKind::PasswordCommandParsingFailed`]: rustic_core::error::RepositoryErrorKind::PasswordCommandParsingFailed
+/// [`RepositoryErrorKind::ReadingPasswordFromCommandFailed`]: rustic_core::error::RepositoryErrorKind::ReadingPasswordFromCommandFailed
 pub(crate) fn init<P, S>(
     repo: Repository<P, S>,
     key_opts: &KeyOptions,

src/commands/key.rs

@@ -1,7 +1,5 @@
 //! `key` subcommand
 
-/// App-local prelude includes `app_reader()`/`app_writer()`/`app_config()`
-/// accessors along with logging macros. Customize as you see fit.
 use crate::{commands::open_repository, status_err, Application, RUSTIC_APP};
 
 use std::path::PathBuf;
@@ -16,6 +14,7 @@ use rustic_core::{KeyOptions, Repository, RepositoryOptions};
 /// `key` subcommand
 #[derive(clap::Parser, Command, Debug)]
 pub(super) struct KeyCmd {
+    /// Subcommand to run
     #[clap(subcommand)]
     cmd: KeySubCmd,
 }
@@ -32,6 +31,7 @@ pub(crate) struct AddCmd {
     #[clap(long)]
     pub(crate) new_password_file: Option<PathBuf>,
 
+    /// Key options
     #[clap(flatten)]
     pub(crate) key_opts: KeyOptions,
 }