diff --git a/CHANGELOG.md b/CHANGELOG.md index ccab9ad..807b1c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ This is a pretty significant release with a large set of breaking changes (yet a Alongside several fields, parameters, and types being renamed, there are three important additions and changes to point out: - `DirectoryScan` has been removed in favor of the new iterator-based `DirectoryScanner` inspired by the wonderful `walkdir` crate, -- directory copy and move function now have options that specify how to behave when encountering valid as well as broken symbolic links, +- directory copy and move functions now have options that specify how to behave when encountering valid as well as broken symbolic links, - the `file_size_in_bytes` function no longer follows symbolic links. diff --git a/src/directory/common.rs b/src/directory/common.rs index 120810b..2e2d0ba 100644 --- a/src/directory/common.rs +++ b/src/directory/common.rs @@ -79,10 +79,10 @@ pub enum CollidingSubDirectoryBehaviour { /// **Do not use [`DestinationDirectoryRule::AllowNonEmpty`] as a default /// unless you're sure you are okay with merged directories.** /// -/// Again, if the destination directory already has some content, -/// this would allow a copy or move that results in a destination directory +/// If the destination directory already has some content, this would +/// allow a copy or move that results in a destination directory /// with *merged* source and destination directory contents. -/// Unless you know you want precisely this, you should probably avoid this option. +/// Unless this is precisely what you're after, you may want to avoid this option. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub enum DestinationDirectoryRule { /// Indicates the associated directory function should return an error, @@ -95,24 +95,31 @@ pub enum DestinationDirectoryRule { /// **This is the default.** AllowEmpty, - /// Indicates that an existing destination directory should not cause an error, - /// even if it is not empty. + /// Indicates that an existing (colliding) destination directory should + /// not cause an error, even if non-empty. /// /// **Do not use this as a default if you're not sure what rule to choose.** - /// This rule can, if the destination directory already has some content, + /// + /// If the destination directory already has some content, this would /// allow a copy or move that results in a destination directory /// with *merged* source and destination directory contents. - /// Unless you know you want precisely this, you should probably avoid this option. + /// Unless this is precisely what you're after, you may want to avoid this option. /// /// Missing destination directories will always be created, /// regardless of the `colliding_subdirectory_behaviour` option. /// Setting it to [`CollidingSubDirectoryBehaviour::Continue`] simply means that - /// if they already exist on the destination, nothing special will happen. + /// if they already exist on the destination, they will not need to be created. AllowNonEmpty { - /// How to behave for destination files that already exist. + /// How to behave when encountering existing (colliding) destination files. + /// + /// This option has no effect on existing destination files + /// that don't collide with the ones we're copying or moving. colliding_file_behaviour: CollidingFileBehaviour, - /// How to behave for destination sub-directories that already exist. + /// How to behave when encountering existing (colliding) destination subdirectories. + /// + /// This option has no effect on existing destination subdirectories + /// that don't collide with the ones we're copying or moving. colliding_subdirectory_behaviour: CollidingSubDirectoryBehaviour, }, } diff --git a/src/file/copy.rs b/src/file/copy.rs index 45e6eee..0502710 100644 --- a/src/file/copy.rs +++ b/src/file/copy.rs @@ -26,7 +26,7 @@ use crate::{ /// Options that influence the [`copy_file`] function. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub struct FileCopyOptions { - /// How to behave for a destination file that already exists. + /// How to behave when the destination file already exists. pub colliding_file_behaviour: CollidingFileBehaviour, } @@ -208,7 +208,7 @@ where /// Options that influence the [`copy_file_with_progress`] function. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub struct FileCopyWithProgressOptions { - /// How to behave for destination files that already exist. + /// How to behave when the destination file already exists. pub colliding_file_behaviour: CollidingFileBehaviour, /// Internal buffer size used for reading the source file. @@ -228,7 +228,7 @@ pub struct FileCopyWithProgressOptions { /// decreasing the interval will likely come at some performance cost, /// depending on your progress handling closure. /// - /// *Note that this is the minimum interval.* The actual reporting interval can be larger. + /// *Note that this is the minimum interval.* The actual reporting interval may be larger! /// Consult [`copy_file_with_progress`] documentation for more details. /// /// Defaults to 512 KiB. diff --git a/src/file/mod.rs b/src/file/mod.rs index 4ebc1bf..ccc011e 100644 --- a/src/file/mod.rs +++ b/src/file/mod.rs @@ -12,7 +12,7 @@ //! | [`move_file`] | [`FileMoveOptions`] | [`FileMoveFinished`]
(or [`FileError`]) | //! | [`move_file_with_progress`] | [`FileMoveWithProgressOptions`] | [`FileMoveFinished`]
(or [`FileError`]) | //! | [`remove_file`] | | `()`
(or [`FileRemoveError`]) | -//! | [`file_size_in_bytes`] | | `()`
(or [`FileSizeError`]) | +//! | [`file_size_in_bytes`] | | [`u64`]
(or [`FileSizeError`]) | //! //! //! [`FileError`]: crate::error::FileError diff --git a/src/file/move.rs b/src/file/move.rs index 269aaed..741ee70 100644 --- a/src/file/move.rs +++ b/src/file/move.rs @@ -23,7 +23,7 @@ use crate::{ /// Options that influence the [`move_file`] function. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub struct FileMoveOptions { - /// How to behave for destination files that already exist. + /// How to behave when the destination file already exists. pub colliding_file_behaviour: CollidingFileBehaviour, } @@ -288,7 +288,7 @@ where /// Options that influence the [`move_file_with_progress`] function. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub struct FileMoveWithProgressOptions { - /// How to behave for destination files that already exist. + /// How to behave when the destination file already exists. pub colliding_file_behaviour: CollidingFileBehaviour, /// Internal buffer size used for reading the source file. diff --git a/src/lib.rs b/src/lib.rs index fe0957b..9cbddf1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -13,7 +13,7 @@ //! //! Visit the **[`directory`]** and **[`file`][mod@file]** modules //! for a deeper overview of the available features. -//!
Also, you can find the error types in the [`error`] module. +//!
Additionally, you can find the error types in the [`error`] module. //! //! //!