From 2b9023e1805176276180ba59ea865093382efb0c Mon Sep 17 00:00:00 2001
From: figsoda <figsoda@pm.me>
Date: Thu, 4 Nov 2021 17:03:52 -0400
Subject: [PATCH] misc comments and wording changes

---
 tests/integration.rs | 19 ++++++++++++++-----
 tests/mime.rs        |  4 ++--
 tests/utils.rs       |  5 ++++-
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/tests/integration.rs b/tests/integration.rs
index 3929378..53eecd3 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -10,10 +10,11 @@ use rand::{rngs::SmallRng, RngCore, SeedableRng};
 use tempfile::tempdir;
 use test_strategy::{proptest, Arbitrary};
 
-use crate::utils::{assert_same_directory, create_file_random};
+use crate::utils::{assert_same_directory, write_random_content};
 
+// tar and zip extensions
 #[derive(Arbitrary, Debug, Display)]
-#[display(style = "snake_case")]
+#[display(style = "lowercase")]
 enum DirectoryExtension {
     Tar,
     Tbz,
@@ -25,8 +26,9 @@ enum DirectoryExtension {
     Zip,
 }
 
+// extensions of single file compression formats
 #[derive(Arbitrary, Debug, Display)]
-#[display(style = "snake_case")]
+#[display(style = "lowercase")]
 enum FileExtension {
     Bz,
     Bz2,
@@ -44,10 +46,12 @@ enum Extension {
     File(FileExtension),
 }
 
+// converts a list of extension structs to string
 fn merge_extensions(ext: impl ToString, exts: Vec<FileExtension>) -> String {
     once(ext.to_string()).chain(exts.into_iter().map(|x| x.to_string())).collect::<Vec<_>>().join(".")
 }
 
+// create random nested directories and files under the specified directory
 fn create_random_files(dir: impl Into<PathBuf>, depth: u8, rng: &mut SmallRng) {
     if depth == 0 {
         return;
@@ -55,15 +59,18 @@ fn create_random_files(dir: impl Into<PathBuf>, depth: u8, rng: &mut SmallRng) {
 
     let dir = &dir.into();
 
+    // create 0 to 7 random files
     for _ in 0..rng.next_u32() % 8 {
-        create_file_random(&mut tempfile::Builder::new().tempfile_in(dir).unwrap().keep().unwrap().0, rng);
+        write_random_content(&mut tempfile::Builder::new().tempfile_in(dir).unwrap().keep().unwrap().0, rng);
     }
 
+    // create more random files in 0 to 3 new directories
     for _ in 0..rng.next_u32() % 4 {
         create_random_files(&tempfile::tempdir_in(dir).unwrap().into_path(), depth - 1, rng);
     }
 }
 
+// compress and decompress a single empty file
 #[proptest(cases = 512)]
 fn single_empty_file(ext: Extension, #[any(size_range(0..8).lift())] exts: Vec<FileExtension>) {
     let dir = tempdir().unwrap();
@@ -73,12 +80,13 @@ fn single_empty_file(ext: Extension, #[any(size_range(0..8).lift())] exts: Vec<F
     let before_file = &before.join("file");
     let archive = &dir.join(format!("file.{}", merge_extensions(ext, exts)));
     let after = &dir.join("after");
-    create_file_random(&mut fs::File::create(before_file).unwrap(), &mut SmallRng::from_entropy());
+    write_random_content(&mut fs::File::create(before_file).unwrap(), &mut SmallRng::from_entropy());
     ouch!("c", before_file, archive);
     ouch!("d", archive, "-d", after);
     assert_same_directory(before, after, false);
 }
 
+// compress and decompress a single file
 #[proptest(cases = 512)]
 fn single_file(ext: Extension, #[any(size_range(0..8).lift())] exts: Vec<FileExtension>) {
     let dir = tempdir().unwrap();
@@ -94,6 +102,7 @@ fn single_file(ext: Extension, #[any(size_range(0..8).lift())] exts: Vec<FileExt
     assert_same_directory(before, after, false);
 }
 
+// compress and decompress a directory with random content generated with create_random_files
 #[proptest(cases = 512)]
 fn multiple_files(
     ext: DirectoryExtension,
diff --git a/tests/mime.rs b/tests/mime.rs
index c88bcb9..0ec73aa 100644
--- a/tests/mime.rs
+++ b/tests/mime.rs
@@ -4,7 +4,7 @@ mod utils;
 use rand::{rngs::SmallRng, SeedableRng};
 use tempfile::NamedTempFile;
 
-use crate::utils::create_file_random;
+use crate::utils::write_random_content;
 
 #[test]
 /// Makes sure that the files ouch produces are what they claim to be, checking their
@@ -14,7 +14,7 @@ fn sanity_check_through_mime() {
     let temp_dir_path = temp_dir.path();
 
     let test_file = &mut NamedTempFile::new_in(temp_dir_path).expect("to be able to build a temporary file");
-    create_file_random(test_file, &mut SmallRng::from_entropy());
+    write_random_content(test_file, &mut SmallRng::from_entropy());
 
     let formats = [
         "tar", "zip", "tar.gz", "tgz", "tbz", "tbz2", "txz", "tlz", "tlzma", "tzst", "tar.bz", "tar.bz2", "tar.lzma",
diff --git a/tests/utils.rs b/tests/utils.rs
index 579bd7b..c4b7baa 100644
--- a/tests/utils.rs
+++ b/tests/utils.rs
@@ -13,12 +13,15 @@ macro_rules! ouch {
     }
 }
 
-pub fn create_file_random(file: &mut impl Write, rng: &mut impl RngCore) {
+// write random content to a file
+pub fn write_random_content(file: &mut impl Write, rng: &mut impl RngCore) {
     let data = &mut Vec::with_capacity((rng.next_u32() % 8192) as usize);
     rng.fill_bytes(data);
     file.write_all(data).unwrap();
 }
 
+// check that two directories have the exact same content recursively
+// checks equility of file types if preserve_permissions is true, ignored on non-unix
 pub fn assert_same_directory(x: impl Into<PathBuf>, y: impl Into<PathBuf>, preserve_permissions: bool) {
     fn read_dir(dir: impl Into<PathBuf>) -> impl Iterator<Item = fs::DirEntry> {
         let mut dir: Vec<_> = fs::read_dir(dir).unwrap().map(|entry| entry.unwrap()).collect();