docs: Fix doc-tests formatting and address other documentation review requests

src/fs/file.rs

@@ -27,9 +27,10 @@ use crate::fs::recursive_size::RecursiveSize;
 use super::mounts::all_mounts;
 use super::mounts::MountedFs;
 
-// Mutex::new is const but HashMap::new is not const requiring us to use lazy
-// initialization. Replace with std::sync::LazyLock when it is stable.
 // Maps (device_id, inode) => (size_in_bytes, size_in_blocks)
+// Mutex::new is const but HashMap::new is not const requiring us to use lazy
+// initialization.
+// TODO: Replace with std::sync::LazyLock when it is stable.
 #[allow(clippy::type_complexity)]
 #[cfg(unix)]
 static DIRECTORY_SIZE_CACHE: Lazy<Mutex<HashMap<(u64, u64), (u64, u64)>>> =

src/fs/recursive_size.rs

@@ -29,6 +29,7 @@ impl RecursiveSize {
     ///
     /// let x = RecursiveSize::Some(0, 0);
     /// assert_eq!(x.is_none(), false);
+    /// ```
     #[inline]
     pub const fn is_none(&self) -> bool {
         matches!(*self, Self::None)
@@ -64,6 +65,7 @@ impl RecursiveSize {
     /// assert_eq!(RecursiveSize::None.map_or(None, |s, _| Some(s * 2)), None);
     /// assert_eq!(RecursiveSize::Unknown.map_or(None, |s, _| Some(s * 2)), None);
     /// assert_eq!(RecursiveSize::Some(2, 3).map_or(None, |s, _| Some(s * 2)), Some(4));
+    /// ```
     #[inline]
     #[cfg_attr(target_family = "windows", allow(dead_code))]
     pub fn map_or<U, F>(self, default: U, f: F) -> U

src/options/help.rs

@@ -65,7 +65,7 @@ LONG VIEW OPTIONS
   -U, --created            use the created timestamp field
   --changed                use the changed timestamp field
   --time-style             how to format timestamps (default, iso, long-iso, full-iso, relative, or a custom style with '+' as prefix. Ex: '+%Y/%m/%d')
-  --total-size             show recursive directory size
+  --total-size             show the size of a directory as the size of all files and directories inside
   --no-permissions         suppress the permissions field
   -o, --octal-permissions  list each file's permission in octal format
   --no-filesize            suppress the filesize field