docs: update documentation for clarity, fix up small nitpicks and errors

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.
 
 

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,
     },
 }

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.

src/file/mod.rs

@@ -12,7 +12,7 @@
 //! | [`move_file`]               | [`FileMoveOptions`]             | [`FileMoveFinished`] <br><sup style="text-align: right">(or [`FileError`])</sup> |
 //! | [`move_file_with_progress`] | [`FileMoveWithProgressOptions`] | [`FileMoveFinished`] <br><sup style="text-align: right">(or [`FileError`])</sup> |
 //! | [`remove_file`]             |                                 | `()` <br><sup style="text-align: right">(or [`FileRemoveError`])</sup> |
-//! | [`file_size_in_bytes`]      |                                 | `()` <br><sup style="text-align: right">(or [`FileSizeError`])</sup> |
+//! | [`file_size_in_bytes`]      |                                 | [`u64`] <br><sup style="text-align: right">(or [`FileSizeError`])</sup> |
 //!
 //!
 //! [`FileError`]: crate::error::FileError

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.

src/lib.rs

@@ -13,7 +13,7 @@
 //!
 //! Visit the **[`directory`]** and **[`file`][mod@file]** modules
 //! for a deeper overview of the available features.
-//! <br> Also, you can find the error types in the [`error`] module.
+//! <br> Additionally, you can find the error types in the [`error`] module.
 //!
 //!
 //! <br>