From 0fdef287c4c191a137f23d6195e28a5dfe276f2a Mon Sep 17 00:00:00 2001
From: Gabriel Simonetto <GabrielSimonetto@users.noreply.github.com>
Date: Wed, 27 Oct 2021 00:08:00 -0300
Subject: [PATCH 1/5] Warn for missing docs, and add necessary docs

---
 src/archive/mod.rs | 2 ++
 src/archive/tar.rs | 2 ++
 src/archive/zip.rs | 1 +
 src/cli.rs         | 5 ++++-
 src/commands.rs    | 9 +++++++++
 src/error.rs       | 3 +++
 src/lib.rs         | 4 +++-
 src/macros.rs      | 1 +
 8 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/archive/mod.rs b/src/archive/mod.rs
index be3f336..e02b432 100644
--- a/src/archive/mod.rs
+++ b/src/archive/mod.rs
@@ -1,2 +1,4 @@
+//! Archive compression algorithms
+
 pub mod tar;
 pub mod zip;
diff --git a/src/archive/tar.rs b/src/archive/tar.rs
index bb52d7e..9720243 100644
--- a/src/archive/tar.rs
+++ b/src/archive/tar.rs
@@ -14,6 +14,7 @@ use crate::{
     utils::{self, Bytes, QuestionPolicy},
 };
 
+/// Unpacks the archive given by `archive` into the folder given by `into`.
 pub fn unpack_archive(
     reader: Box<dyn Read>,
     output_folder: &Path,
@@ -40,6 +41,7 @@ pub fn unpack_archive(
     Ok(files_unpacked)
 }
 
+/// Compresses the archives given by `input_filenames` into the file given previously to `writer`.
 pub fn build_archive_from_paths<W>(input_filenames: &[PathBuf], writer: W) -> crate::Result<W>
 where
     W: Write,
diff --git a/src/archive/zip.rs b/src/archive/zip.rs
index 87d1a17..ca1855c 100644
--- a/src/archive/zip.rs
+++ b/src/archive/zip.rs
@@ -70,6 +70,7 @@ where
     Ok(unpacked_files)
 }
 
+/// Compresses the archives given by `input_filenames` into the file given previously to `writer`.
 pub fn build_archive_from_paths<W>(input_filenames: &[PathBuf], writer: W) -> crate::Result<W>
 where
     W: Write + Seek,
diff --git a/src/cli.rs b/src/cli.rs
index 1ec281b..e725e44 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -10,6 +10,7 @@ use clap::{Parser, ValueHint};
 pub use crate::utils::QuestionPolicy;
 use crate::Error;
 
+/// Command line options
 #[derive(Parser, Debug)]
 #[clap(version, about)]
 pub struct Opts {
@@ -21,10 +22,12 @@ pub struct Opts {
     #[clap(short, long)]
     pub no: bool,
 
+    /// Action to take
     #[clap(subcommand)]
     pub cmd: Subcommand,
 }
 
+/// Actions to take
 #[derive(Parser, PartialEq, Eq, Debug)]
 pub enum Subcommand {
     /// Compress files.    Alias: c
@@ -38,7 +41,7 @@ pub enum Subcommand {
         #[clap(required = true, value_hint = ValueHint::FilePath)]
         output: PathBuf,
     },
-    /// Compress files.    Alias: d
+    /// Decompress files.    Alias: d
     #[clap(alias = "d")]
     Decompress {
         /// Files to be decompressed
diff --git a/src/commands.rs b/src/commands.rs
index 2543c67..49e7d0c 100644
--- a/src/commands.rs
+++ b/src/commands.rs
@@ -38,6 +38,8 @@ fn represents_several_files(files: &[PathBuf]) -> bool {
     files.iter().any(is_non_empty_dir) || files.len() > 1
 }
 
+/// Entrypoint of ouch, receives cli options and matches Subcommand
+/// to decide current operation
 pub fn run(args: Opts, question_policy: QuestionPolicy) -> crate::Result<()> {
     match args.cmd {
         Subcommand::Compress { files, output: output_path } => {
@@ -183,6 +185,11 @@ pub fn run(args: Opts, question_policy: QuestionPolicy) -> crate::Result<()> {
     Ok(())
 }
 
+// Compress files into an `output_file`
+//
+// files are the list of paths to be compressed: ["dir/file1.txt", "dir/file2.txt"]
+// formats contains each format necessary for compression, example: [Tar, Gz] (in compression order)
+// output_file is the resulting compressed file name, example: "compressed.tar.gz"
 fn compress_files(files: Vec<PathBuf>, formats: Vec<CompressionFormat>, output_file: fs::File) -> crate::Result<()> {
     let file_writer = BufWriter::with_capacity(BUFFER_CAPACITY, output_file);
 
@@ -280,6 +287,8 @@ fn compress_files(files: Vec<PathBuf>, formats: Vec<CompressionFormat>, output_f
     Ok(())
 }
 
+// Decompress a file
+//
 // File at input_file_path is opened for reading, example: "archive.tar.gz"
 // formats contains each format necessary for decompression, example: [Gz, Tar] (in decompression order)
 // output_folder it's where the file will be decompressed to
diff --git a/src/error.rs b/src/error.rs
index a8dd654..114f580 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -6,6 +6,8 @@
 //! TODO: wrap `FinalError` in a variant to keep all `FinalError::display_and_crash()` function
 //! calls inside of this module.
 
+#![allow(missing_docs)]
+
 use std::{
     fmt::{self, Display},
     path::{Path, PathBuf},
@@ -13,6 +15,7 @@ use std::{
 
 use crate::utils::colors::*;
 
+/// Custom Ouch Errors
 #[derive(Debug, PartialEq)]
 pub enum Error {
     UnknownExtensionError(String),
diff --git a/src/lib.rs b/src/lib.rs
index 9a1a795..3edee45 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,12 +4,14 @@
 //! 1. It's required by `main.rs`, or
 //! 2. It's required by some integration tests at tests/ folder.
 
+#![warn(missing_docs)]
+
 // Public modules
+pub mod archive;
 pub mod cli;
 pub mod commands;
 
 // Private modules
-pub mod archive;
 mod dialogs;
 mod error;
 mod extension;
diff --git a/src/macros.rs b/src/macros.rs
index 76877fa..c570831 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -1,4 +1,5 @@
 #[macro_export]
+/// Macro that prints message in INFO mode
 macro_rules! info {
     ($($arg:tt)*) => {
         $crate::macros::_info_helper();

From 70b787b58e85ada364f1108d103f0dcc5e3d3939 Mon Sep 17 00:00:00 2001
From: Gabriel Simonetto <GabrielSimonetto@users.noreply.github.com>
Date: Wed, 27 Oct 2021 00:08:26 -0300
Subject: [PATCH 2/5] Fix repo link on documentation

---
 Cargo.toml   | 2 +-
 src/error.rs | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index c42ac8b..45282d2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.2.0"
 authors = ["Vinícius Rodrigues Miguel <vrmiguel99@gmail.com>", "João M. Bezerra <marcospb19@hotmail.com>"]
 edition = "2018"
 readme = "README.md"
-repository = "https://github.com/vrmiguel/ouch"
+repository = "https://github.com/ouch-org/ouch"
 license = "MIT"
 keywords = ["decompression", "compression", "zip", "tar", "gzip"]
 categories = ["command-line-utilities", "compression", "encoding"]
diff --git a/src/error.rs b/src/error.rs
index 114f580..63ea6d7 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -90,7 +90,7 @@ impl fmt::Display for Error {
                 FinalError::with_title(format!("Cannot compress to {:?}", filename))
                     .detail("Ouch could not detect the compression format")
                     .hint("Use a supported format extension, like '.zip' or '.tar.gz'")
-                    .hint("Check https://github.com/vrmiguel/ouch for a full list of supported formats")
+                    .hint("Check https://github.com/ouch-org/ouch for a full list of supported formats")
             }
             Error::WalkdirError { reason } => FinalError::with_title(reason),
             Error::FileNotFound(file) => {
@@ -127,7 +127,7 @@ impl fmt::Display for Error {
                     .detail("This should not have happened")
                     .detail("It's probably our fault")
                     .detail("Please help us improve by reporting the issue at:")
-                    .detail(format!("    {}https://github.com/vrmiguel/ouch/issues ", *CYAN))
+                    .detail(format!("    {}https://github.com/ouch-org/ouch/issues ", *CYAN))
             }
             Error::IoError { reason } => FinalError::with_title(reason),
             Error::CompressionTypo => {

From 7c82f2b3b72b41763b29df001116cfb3d9cb73d2 Mon Sep 17 00:00:00 2001
From: Gabriel Simonetto <GabrielSimonetto@users.noreply.github.com>
Date: Sat, 30 Oct 2021 15:34:39 -0300
Subject: [PATCH 3/5] Make remaining modules public in order to gain the
 documentation check

---
 src/dialogs.rs   |  7 +++++++
 src/extension.rs | 23 +++++++++++++++++++++++
 src/lib.rs       | 12 +++++-------
 src/macros.rs    |  3 +++
 src/utils.rs     | 15 ++++++++++++++-
 5 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/src/dialogs.rs b/src/dialogs.rs
index 4f4d7b2..ce18102 100644
--- a/src/dialogs.rs
+++ b/src/dialogs.rs
@@ -12,15 +12,22 @@ use crate::utils::colors;
 
 /// Represents a confirmation dialog
 pub struct Confirmation<'a> {
+    /// Represents the message to the displayed
+    /// e.g.: "Do you want to overwrite 'FILE'?"
     pub prompt: &'a str,
+
+    /// Represents a placeholder to be changed at runtime
+    /// e.g.: Some("FILE")
     pub placeholder: Option<&'a str>,
 }
 
 impl<'a> Confirmation<'a> {
+    /// New Confirmation
     pub const fn new(prompt: &'a str, pattern: Option<&'a str>) -> Self {
         Self { prompt, placeholder: pattern }
     }
 
+    /// Creates user message and receives a boolean input to be used on the program
     pub fn ask(&self, substitute: Option<&'a str>) -> crate::Result<bool> {
         let message = match (self.placeholder, substitute) {
             (None, _) => Cow::Borrowed(self.prompt),
diff --git a/src/extension.rs b/src/extension.rs
index b1828f0..8ef479c 100644
--- a/src/extension.rs
+++ b/src/extension.rs
@@ -4,6 +4,7 @@ use std::{ffi::OsStr, fmt, path::Path};
 
 use self::CompressionFormat::*;
 
+#[allow(missing_docs)]
 #[derive(Clone, PartialEq, Eq, Debug)]
 /// Accepted extensions for input and output
 pub enum CompressionFormat {
@@ -40,6 +41,19 @@ impl fmt::Display for CompressionFormat {
     }
 }
 
+// use crate::extension::CompressionFormat::*;
+//
+
+/// Extracts extensions from a path,
+/// return both the remaining path and the list of extension objects
+///
+/// ```rust
+/// use ouch::extension::{separate_known_extensions_from_name, CompressionFormat};
+/// use std::path::Path;
+///
+/// let mut path = Path::new("bolovo.tar.gz");
+/// assert_eq!(separate_known_extensions_from_name(&path), (Path::new("bolovo"), vec![CompressionFormat::Tar, CompressionFormat::Gzip]));
+/// ```
 pub fn separate_known_extensions_from_name(mut path: &Path) -> (&Path, Vec<CompressionFormat>) {
     // // TODO: check for file names with the name of an extension
     // // TODO2: warn the user that currently .tar.gz is a .gz file named .tar
@@ -76,6 +90,15 @@ pub fn separate_known_extensions_from_name(mut path: &Path) -> (&Path, Vec<Compr
     (path, extensions)
 }
 
+/// Extracts extensions from a path, return only the list of extension objects
+///
+/// ```rust
+/// use ouch::extension::{extensions_from_path, CompressionFormat};
+/// use std::path::Path;
+///
+/// let mut path = Path::new("bolovo.tar.gz");
+/// assert_eq!(extensions_from_path(&path), vec![CompressionFormat::Tar, CompressionFormat::Gzip]);
+/// ```
 pub fn extensions_from_path(path: &Path) -> Vec<CompressionFormat> {
     let (_, extensions) = separate_known_extensions_from_name(path);
     extensions
diff --git a/src/lib.rs b/src/lib.rs
index 3edee45..24394b2 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,13 +10,11 @@
 pub mod archive;
 pub mod cli;
 pub mod commands;
-
-// Private modules
-mod dialogs;
-mod error;
-mod extension;
-mod macros;
-mod utils;
+pub mod dialogs;
+pub mod error;
+pub mod extension;
+pub mod macros;
+pub mod utils;
 
 pub use error::{Error, Result};
 
diff --git a/src/macros.rs b/src/macros.rs
index c570831..4a16e8c 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -1,3 +1,5 @@
+//! Macros used on ouch.
+
 #[macro_export]
 /// Macro that prints message in INFO mode
 macro_rules! info {
@@ -7,6 +9,7 @@ macro_rules! info {
     };
 }
 
+/// Prints the `[Info]` tag
 pub fn _info_helper() {
     use crate::utils::colors::{RESET, YELLOW};
 
diff --git a/src/utils.rs b/src/utils.rs
index 7c3a0e7..d407533 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -1,3 +1,5 @@
+//! Utils used on ouch.
+
 use std::{
     cmp, env,
     ffi::OsStr,
@@ -15,6 +17,7 @@ pub fn dir_is_empty(dir_path: &Path) -> bool {
     dir_path.read_dir().map(is_empty).unwrap_or_default()
 }
 
+/// Creates the dir if non existent.
 pub fn create_dir_if_non_existent(path: &Path) -> crate::Result<()> {
     if !path.exists() {
         fs::create_dir_all(path)?;
@@ -23,6 +26,9 @@ pub fn create_dir_if_non_existent(path: &Path) -> crate::Result<()> {
     Ok(())
 }
 
+/// Removes the current dir from the beginning of a path
+/// normally used for presentation sake.
+/// If this function fails, it will return source path as a PathBuf.
 pub fn strip_cur_dir(source_path: &Path) -> PathBuf {
     source_path
         .strip_prefix(Component::CurDir)
@@ -43,6 +49,8 @@ pub fn cd_into_same_dir_as(filename: &Path) -> crate::Result<PathBuf> {
     Ok(previous_location)
 }
 
+/// Centralizes the decision of overwriting a file or not,
+/// whether the user has already passed a question_policy or not.
 pub fn user_wants_to_overwrite(path: &Path, question_policy: QuestionPolicy) -> crate::Result<bool> {
     match question_policy {
         QuestionPolicy::AlwaysYes => Ok(true),
@@ -56,11 +64,13 @@ pub fn user_wants_to_overwrite(path: &Path, question_policy: QuestionPolicy) ->
     }
 }
 
+/// Converts an OsStr to utf8.
 pub fn to_utf(os_str: impl AsRef<OsStr>) -> String {
     let text = format!("{:?}", os_str.as_ref());
     text.trim_matches('"').to_string()
 }
 
+/// Treats weird paths for better user messages.
 pub fn nice_directory_display(os_str: impl AsRef<OsStr>) -> String {
     let text = to_utf(os_str);
     if text == "." {
@@ -70,6 +80,7 @@ pub fn nice_directory_display(os_str: impl AsRef<OsStr>) -> String {
     }
 }
 
+/// Struct used to overload functionality onto Byte presentation.
 pub struct Bytes {
     bytes: f64,
 }
@@ -86,6 +97,7 @@ pub mod colors {
     macro_rules! color {
         ($name:ident = $value:literal) => {
             #[cfg(target_family = "unix")]
+            /// Inserts color onto text based on configuration
             pub static $name: Lazy<&str> = Lazy::new(|| if *DISABLE_COLORED_TEXT { "" } else { $value });
             #[cfg(not(target_family = "unix"))]
             pub static $name: &&str = &"";
@@ -106,6 +118,7 @@ pub mod colors {
 impl Bytes {
     const UNIT_PREFIXES: [&'static str; 6] = ["", "k", "M", "G", "T", "P"];
 
+    /// New Byte structure
     pub fn new(bytes: u64) -> Self {
         Self { bytes: bytes as f64 }
     }
@@ -129,7 +142,7 @@ impl std::fmt::Display for Bytes {
 #[derive(Debug, PartialEq, Clone, Copy)]
 /// How overwrite questions should be handled
 pub enum QuestionPolicy {
-    /// Ask ever time
+    /// Ask everytime
     Ask,
     /// Skip overwrite questions positively
     AlwaysYes,

From 20e0067cad5236eb9c79c4f3ada7ce294ea8674b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20M=2E=20Bezerra?= <marcospb19@hotmail.com>
Date: Sun, 31 Oct 2021 03:03:31 -0300
Subject: [PATCH 4/5] Adding docs in new files and functions

---
 src/cli.rs       | 4 +++-
 src/extension.rs | 1 +
 src/lib.rs       | 4 +++-
 src/macros.rs    | 2 +-
 src/opts.rs      | 4 ++++
 5 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 4ef39ec..cd853de 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1,4 +1,6 @@
-//! CLI arg parser configuration, command detection and input treatment.
+//! CLI configuration step, uses definitions from `opts.rs`.
+//!
+//! Also used to treat some inputs.
 
 use std::{
     path::{Path, PathBuf},
diff --git a/src/extension.rs b/src/extension.rs
index 346351f..3cd17d6 100644
--- a/src/extension.rs
+++ b/src/extension.rs
@@ -21,6 +21,7 @@ pub enum CompressionFormat {
 }
 
 impl CompressionFormat {
+    /// Currently supported archive formats are .tar (and aliases to it) and .zip
     pub fn is_archive_format(&self) -> bool {
         matches!(self, Tar | Tgz | Tbz | Tlzma | Tzst | Zip)
     }
diff --git a/src/lib.rs b/src/lib.rs
index 80ca62f..7793a35 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -6,13 +6,15 @@
 
 #![warn(missing_docs)]
 
+// Macros should be declared before
+pub mod macros;
+
 pub mod archive;
 pub mod cli;
 pub mod commands;
 pub mod dialogs;
 pub mod error;
 pub mod extension;
-pub mod macros;
 pub mod opts;
 pub mod utils;
 
diff --git a/src/macros.rs b/src/macros.rs
index 4a16e8c..5bf7205 100644
--- a/src/macros.rs
+++ b/src/macros.rs
@@ -1,7 +1,7 @@
 //! Macros used on ouch.
 
-#[macro_export]
 /// Macro that prints message in INFO mode
+#[macro_export]
 macro_rules! info {
     ($($arg:tt)*) => {
         $crate::macros::_info_helper();
diff --git a/src/opts.rs b/src/opts.rs
index 24bc299..75842cc 100644
--- a/src/opts.rs
+++ b/src/opts.rs
@@ -1,7 +1,9 @@
+//! CLI configuration step, uses definitions from `opts.rs`, also used to treat some inputs.
 use clap::{Parser, ValueHint};
 
 use std::path::PathBuf;
 
+/// Command line options
 #[derive(Parser, Debug)]
 #[clap(version, about)]
 pub struct Opts {
@@ -13,10 +15,12 @@ pub struct Opts {
     #[clap(short, long)]
     pub no: bool,
 
+    /// Action to take
     #[clap(subcommand)]
     pub cmd: Subcommand,
 }
 
+/// Actions to take
 #[derive(Parser, PartialEq, Eq, Debug)]
 pub enum Subcommand {
     /// Compress files.    Alias: c

From d9e0b4c5fbf6cc2c14772a4e634617ee7fd6fc4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20M=2E=20Bezerra?= <marcospb19@hotmail.com>
Date: Sun, 31 Oct 2021 12:57:30 -0300
Subject: [PATCH 5/5] Fixing documentation conflicting with build.rs

---
 src/lib.rs  | 4 +++-
 src/opts.rs | 1 -
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 7793a35..40384a6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -15,9 +15,11 @@ pub mod commands;
 pub mod dialogs;
 pub mod error;
 pub mod extension;
-pub mod opts;
 pub mod utils;
 
+/// CLI configuration step, uses definitions from `opts.rs`, also used to treat some inputs.
+pub mod opts;
+
 pub use error::{Error, Result};
 pub use opts::{Opts, Subcommand};
 pub use utils::QuestionPolicy;
diff --git a/src/opts.rs b/src/opts.rs
index 75842cc..243a5a0 100644
--- a/src/opts.rs
+++ b/src/opts.rs
@@ -1,4 +1,3 @@
-//! CLI configuration step, uses definitions from `opts.rs`, also used to treat some inputs.
 use clap::{Parser, ValueHint};
 
 use std::path::PathBuf;