From 89d1e6a752cd3d4cad379abeb024b913290d60af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20M=2E=20Bezerra?= <marcospb19@hotmail.com>
Date: Sun, 3 Oct 2021 00:17:57 -0300
Subject: [PATCH] Document modules

---
 src/cli.rs       | 4 ++++
 src/commands.rs  | 4 ++++
 src/dialogs.rs   | 7 ++++++-
 src/error.rs     | 8 ++++++++
 src/extension.rs | 4 +++-
 src/lib.rs       | 6 ++++++
 src/macros.rs    | 1 -
 src/oof/error.rs | 2 ++
 tests/utils.rs   | 2 ++
 9 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 302d371..2f8b499 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1,3 +1,7 @@
+//! CLI argparser configuration, command detection and input treatment.
+//!
+//! NOTE: the argparser implementation itself is not in this file.
+
 use std::{
     env,
     ffi::OsString,
diff --git a/src/commands.rs b/src/commands.rs
index 1e1a4b0..000c5b5 100644
--- a/src/commands.rs
+++ b/src/commands.rs
@@ -1,3 +1,7 @@
+//! Core of the crate, where the `compress_files` and `decompress_file` functions are implemented
+//!
+//! Also, where correctly call functions based on the detected `Command`.
+
 use std::{
     fs,
     io::{self, BufReader, BufWriter, Read, Write},
diff --git a/src/dialogs.rs b/src/dialogs.rs
index c71e5ec..95db53f 100644
--- a/src/dialogs.rs
+++ b/src/dialogs.rs
@@ -1,3 +1,8 @@
+//! Pretty (and colored) dialog for asking [Y/n] for the end user.
+//!
+//! Example:
+//!     "Do you want to overwrite 'archive.targz'? [Y/n]"
+
 use std::{
     borrow::Cow,
     io::{self, Write},
@@ -38,7 +43,7 @@ impl<'a> Confirmation<'a> {
             match trimmed_answer.to_ascii_lowercase().as_ref() {
                 "y" | "yes" => return Ok(true),
                 "n" | "no" => return Ok(false),
-                _ => {}
+                _ => continue, // Try again
             }
         }
     }
diff --git a/src/error.rs b/src/error.rs
index dbf70d0..0169fed 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -1,3 +1,11 @@
+//! Error type definitions.
+//!
+//! All the unexpected user-side errors should be treated in this file, that does not include
+//! errors made by devs in our implementation.
+//!
+//! TODO: wrap `FinalError` in a variant to keep all `FinalError::display_and_crash()` function
+//! calls inside of this module.
+
 use std::{
     fmt::{self, Display},
     path::{Path, PathBuf},
diff --git a/src/extension.rs b/src/extension.rs
index 0532831..1e77165 100644
--- a/src/extension.rs
+++ b/src/extension.rs
@@ -1,6 +1,8 @@
+//! Our representation of all the supported compression formats.
+
 use std::{fmt, path::Path};
 
-use CompressionFormat::*;
+use self::CompressionFormat::*;
 
 #[derive(Clone, PartialEq, Eq, Debug)]
 /// Accepted extensions for input and output
diff --git a/src/lib.rs b/src/lib.rs
index 58a9879..9b8a109 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,9 @@
+//! This library is meant to be published, just used internally by our binary crate at `main.rs`.
+//!
+//! A module shall be public only if:
+//! 1. It's required by `main.rs`, or
+//! 2. It's required by some integration tests at tests/ folder.
+
 // Public modules
 pub mod cli;
 pub mod commands;
diff --git a/src/macros.rs b/src/macros.rs
index 723f364..bed8ba9 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -2,7 +2,6 @@ use crate::NO_COLOR_IS_SET;
 
 #[macro_export]
 macro_rules! info {
-
     ($writer:expr, $($arg:tt)*) => {
         use crate::macros::_info_helper;
         _info_helper();
diff --git a/src/oof/error.rs b/src/oof/error.rs
index ff47f0a..6dd4783 100644
--- a/src/oof/error.rs
+++ b/src/oof/error.rs
@@ -1,3 +1,5 @@
+//! Errors related to argparsing.
+
 use std::{error, ffi::OsString, fmt};
 
 use super::Flag;
diff --git a/tests/utils.rs b/tests/utils.rs
index 615cce4..3ab9831 100644
--- a/tests/utils.rs
+++ b/tests/utils.rs
@@ -1,3 +1,5 @@
+//! Files in common between one or more integration tests
+
 #![allow(dead_code)]
 
 use std::{