diff --git a/crates/rustic_core/src/backend.rs b/crates/rustic_core/src/backend.rs index 7cef48863..20b5b3623 100644 --- a/crates/rustic_core/src/backend.rs +++ b/crates/rustic_core/src/backend.rs @@ -153,9 +153,13 @@ pub trait WriteBackend: ReadBackend { } #[derive(Debug, Clone)] +/// Information about an entry to be able to open it. pub struct ReadSourceEntry { + /// The path of the entry. pub path: PathBuf, + /// The node information of the entry. pub node: Node, + /// Information about how to open the entry. pub open: Option, } diff --git a/crates/rustic_core/src/backend/local.rs b/crates/rustic_core/src/backend/local.rs index 77cb14962..b14c30d9e 100644 --- a/crates/rustic_core/src/backend/local.rs +++ b/crates/rustic_core/src/backend/local.rs @@ -258,12 +258,19 @@ impl WriteBackend for LocalBackend { } #[derive(Clone, Debug)] +/// Local destination, used when restoring. pub struct LocalDestination { path: PathBuf, is_file: bool, } impl LocalDestination { + /// Create a new [`LocalDestination`] + /// + /// Arguments: + /// - `path`: The base path of the destination + /// - `create`: If `create` is true, create the base path if it doesn't exist. + /// - `expect_file`: Whether we expect a single file as destination. pub fn new(path: &str, create: bool, expect_file: bool) -> RusticResult { let is_dir = path.ends_with('/'); let path: PathBuf = path.into(); @@ -290,20 +297,24 @@ impl LocalDestination { } } + /// Remove the given dir (relative to the base path) pub fn remove_dir(&self, dirname: impl AsRef) -> RusticResult<()> { Ok(fs::remove_dir_all(dirname).map_err(LocalErrorKind::DirectoryRemovalFailed)?) } + /// Remove the given file (relative to the base path) pub fn remove_file(&self, filename: impl AsRef) -> RusticResult<()> { Ok(fs::remove_file(filename).map_err(LocalErrorKind::FileRemovalFailed)?) } + /// Create the given dir (relative to the base path) pub fn create_dir(&self, item: impl AsRef) -> RusticResult<()> { let dirname = self.path.join(item); fs::create_dir_all(dirname).map_err(LocalErrorKind::DirectoryCreationFailed)?; Ok(()) } + /// Set times for `item` (relative to the base path) from `meta` pub fn set_times(&self, item: impl AsRef, meta: &Metadata) -> RusticResult<()> { let filename = self.path(item); if let Some(mtime) = meta.mtime { @@ -321,6 +332,7 @@ impl LocalDestination { #[cfg(windows)] // TODO: Windows support + /// Set user/group for `item` (relative to the base path) from `meta` pub fn set_user_group(&self, _item: impl AsRef, _meta: &Metadata) -> RusticResult<()> { // https://learn.microsoft.com/en-us/windows/win32/fileio/file-security-and-access-rights // https://microsoft.github.io/windows-docs-rs/doc/windows/Win32/Security/struct.SECURITY_ATTRIBUTES.html @@ -329,6 +341,7 @@ impl LocalDestination { } #[cfg(not(windows))] + /// Set user/group for `item` (relative to the base path) from `meta` pub fn set_user_group(&self, item: impl AsRef, meta: &Metadata) -> RusticResult<()> { let filename = self.path(item); @@ -353,11 +366,13 @@ impl LocalDestination { #[cfg(windows)] // TODO: Windows support + /// Set uid/gid for `item` (relative to the base path) from `meta` pub fn set_uid_gid(&self, _item: impl AsRef, _meta: &Metadata) -> RusticResult<()> { Ok(()) } #[cfg(not(windows))] + /// Set uid/gid for `item` (relative to the base path) from `meta` pub fn set_uid_gid(&self, item: impl AsRef, meta: &Metadata) -> RusticResult<()> { let filename = self.path(item); @@ -371,11 +386,13 @@ impl LocalDestination { #[cfg(windows)] // TODO: Windows support + /// Set permissions for `item` (relative to the base path) from `meta` pub fn set_permission(&self, _item: impl AsRef, _node: &Node) -> RusticResult<()> { Ok(()) } #[cfg(not(windows))] + /// Set permissions for `item` (relative to the base path) from `meta` pub fn set_permission(&self, item: impl AsRef, node: &Node) -> RusticResult<()> { if node.is_symlink() { return Ok(()); @@ -394,6 +411,7 @@ impl LocalDestination { #[cfg(any(windows, target_os = "openbsd"))] // TODO: Windows support // TODO: openbsd support + /// Set extended attributes for `item` (relative to the base path) pub fn set_extended_attributes( &self, _item: impl AsRef, @@ -403,6 +421,7 @@ impl LocalDestination { } #[cfg(not(any(windows, target_os = "openbsd")))] + /// Set extended attributes for `item` (relative to the base path) pub fn set_extended_attributes( &self, item: impl AsRef, @@ -459,7 +478,9 @@ impl LocalDestination { Ok(()) } - // set_length sets the length of the given file. If it doesn't exist, create a new (empty) one with given length + /// Set length of `item` (relative to the base path) + /// + // If it doesn't exist, create a new (empty) one with given length pub fn set_length(&self, item: impl AsRef, size: u64) -> RusticResult<()> { let filename = self.path(item); let dir = filename @@ -479,11 +500,13 @@ impl LocalDestination { #[cfg(windows)] // TODO: Windows support + /// Create a special file (relative to the base path) pub fn create_special(&self, _item: impl AsRef, _node: &Node) -> RusticResult<()> { Ok(()) } #[cfg(not(windows))] + /// Create a special file (relative to the base path) pub fn create_special(&self, item: impl AsRef, node: &Node) -> RusticResult<()> { let filename = self.path(item); @@ -537,6 +560,7 @@ impl LocalDestination { Ok(()) } + /// Read the given item (relative to the base path) pub fn read_at(&self, item: impl AsRef, offset: u64, length: u64) -> RusticResult { let filename = self.path(item); let mut file = File::open(filename).map_err(LocalErrorKind::OpeningFileFailed)?; @@ -549,6 +573,9 @@ impl LocalDestination { Ok(vec.into()) } + /// Check if amatching file exists. + /// If a file exists and size matches, this returns a `File` open for reading. + /// In all other cases, retruns `None` pub fn get_matching_file(&self, item: impl AsRef, size: u64) -> Option { let filename = self.path(item); fs::symlink_metadata(&filename).map_or_else( @@ -563,6 +590,7 @@ impl LocalDestination { ) } + /// Write `data`to given item (relative to the base path) at `offset` pub fn write_at(&self, item: impl AsRef, offset: u64, data: &[u8]) -> RusticResult<()> { let filename = self.path(item); let mut file = fs::OpenOptions::new() diff --git a/crates/rustic_core/src/blob.rs b/crates/rustic_core/src/blob.rs index 2bd78a563..0f3a11f1d 100644 --- a/crates/rustic_core/src/blob.rs +++ b/crates/rustic_core/src/blob.rs @@ -56,6 +56,7 @@ impl Initialize for BlobTypeMap { /// Sum is a new trait to define the method sum() for a `BlobTypeMap` pub trait Sum { + /// compute the sum fn sum(&self) -> T; } diff --git a/crates/rustic_core/src/commands/repair/index.rs b/crates/rustic_core/src/commands/repair/index.rs index d86c39611..19dab5973 100644 --- a/crates/rustic_core/src/commands/repair/index.rs +++ b/crates/rustic_core/src/commands/repair/index.rs @@ -22,7 +22,7 @@ use crate::{ #[non_exhaustive] /// Options for the `repair index` command pub struct RepairIndexOptions { - // Read all data packs, i.e. completely re-create the index + /// Read all data packs, i.e. completely re-create the index #[cfg_attr(feature = "clap", clap(long))] pub read_all: bool, } diff --git a/crates/rustic_core/src/commands/restore.rs b/crates/rustic_core/src/commands/restore.rs index e98350d8f..875c8fcc0 100644 --- a/crates/rustic_core/src/commands/restore.rs +++ b/crates/rustic_core/src/commands/restore.rs @@ -591,6 +591,9 @@ impl RestorePlan { } } + /// Get a list of all pack files needed to perform the restore + /// + /// This can be used e.g. to warm-up those pack files before doing the atual restore. pub fn to_packs(&self) -> Vec { self.r .iter() diff --git a/crates/rustic_core/src/error.rs b/crates/rustic_core/src/error.rs index 0597fd33f..0d246d6e6 100644 --- a/crates/rustic_core/src/error.rs +++ b/crates/rustic_core/src/error.rs @@ -24,17 +24,18 @@ use thiserror::Error; use crate::{backend::node::NodeType, id::Id, repofile::indexfile::IndexPack}; -/// Result type often returned from methods that can have rustic `Error`s. +/// Result type often returned from methods that can have `RusticError`s. pub type RusticResult = Result; // [`Error`] is public, but opaque and easy to keep compatible. #[derive(Error, Debug)] #[error(transparent)] +/// Errors that can result from rustic. pub struct RusticError(#[from] RusticErrorKind); // Accessors for anything we do want to expose publicly. impl RusticError { - pub fn into_inner(self) -> RusticErrorKind { + pub(crate) fn into_inner(self) -> RusticErrorKind { self.0 } } diff --git a/crates/rustic_core/src/lib.rs b/crates/rustic_core/src/lib.rs index 05c8af7bf..0e1aa7511 100644 --- a/crates/rustic_core/src/lib.rs +++ b/crates/rustic_core/src/lib.rs @@ -34,7 +34,6 @@ This crate exposes a few features for controlling dependency usage. #![forbid(unsafe_code)] #![warn( // unreachable_pub, // frequently check - // TODO: Activate and create better docs missing_docs, rust_2018_idioms, trivial_casts, diff --git a/crates/rustic_core/src/progress.rs b/crates/rustic_core/src/progress.rs index 2ba552420..5a54975d2 100644 --- a/crates/rustic_core/src/progress.rs +++ b/crates/rustic_core/src/progress.rs @@ -20,6 +20,7 @@ pub trait Progress: Send + Sync + Clone { /// Trait to start progress information report progress information for any rustic action which supports that. /// Implement this trait when you want to display this progress to your users. pub trait ProgressBars { + /// The actual type which is able to show the progress type P: Progress; /// Start a new progress, which is hidden fn progress_hidden(&self) -> Self::P; @@ -32,6 +33,7 @@ pub trait ProgressBars { } #[derive(Clone, Copy, Debug)] +/// A dummy struct which shows no progress but only logs titles and end of a progress. pub struct NoProgress; impl Progress for NoProgress { fn is_hidden(&self) -> bool { @@ -48,6 +50,7 @@ impl Progress for NoProgress { } #[derive(Clone, Copy, Debug)] +/// Don't show progress bars, only log rudimentary progress information. pub struct NoProgressBars; impl ProgressBars for NoProgressBars { type P = NoProgress;