Change existing method docs to valid rustdoc

src/commands/decompress.rs

@@ -18,12 +18,12 @@ use crate::{
     QuestionAction, QuestionPolicy, BUFFER_CAPACITY,
 };
 
-// Decompress a file
+/// Decompress a file
-//
+///
-// File at input_file_path is opened for reading, example: "archive.tar.gz"
+/// 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)
+/// formats contains each format necessary for decompression, example: [Gz, Tar] (in decompression order)
-// output_dir it's where the file will be decompressed to, this function assumes that the directory exists
+/// output_dir it's where the file will be decompressed to, this function assumes that the directory exists
-// output_file_path is only used when extracting single file formats, not archive formats like .tar or .zip
+/// output_file_path is only used when extracting single file formats, not archive formats like .tar or .zip
 pub fn decompress_file(
     input_file_path: &Path,
     formats: Vec<Extension>,

src/commands/list.rs

@@ -13,8 +13,8 @@ use crate::{
     QuestionAction, QuestionPolicy, BUFFER_CAPACITY,
 };
 
-// File at input_file_path is opened for reading, example: "archive.tar.gz"
+/// 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)
+/// formats contains each format necessary for decompression, example: [Gz, Tar] (in decompression order)
 pub fn list_archive_contents(
     archive_path: &Path,
     formats: Vec<CompressionFormat>,

src/extension.rs

@@ -197,7 +197,7 @@ pub fn extensions_from_path(path: &Path) -> Vec<Extension> {
     extensions
 }
 
-// Panics if formats has an empty list of compression formats
+/// Panics if formats has an empty list of compression formats
 pub fn split_first_compression_format(formats: &[Extension]) -> (CompressionFormat, Vec<CompressionFormat>) {
     let mut extensions: Vec<CompressionFormat> = flatten_compression_formats(formats);
     let first_extension = extensions.remove(0);

tests/integration.rs

@@ -12,7 +12,7 @@ use test_strategy::{proptest, Arbitrary};
 
 use crate::utils::{assert_same_directory, write_random_content};
 
-// tar and zip extensions
+/// tar and zip extensions
 #[derive(Arbitrary, Debug, Display)]
 #[display(style = "lowercase")]
 enum DirectoryExtension {
@@ -30,7 +30,7 @@ enum DirectoryExtension {
     Zip,
 }
 
-// extensions of single file compression formats
+/// Extensions of single file compression formats
 #[derive(Arbitrary, Debug, Display)]
 #[display(style = "lowercase")]
 enum FileExtension {
@@ -51,7 +51,7 @@ enum Extension {
     File(FileExtension),
 }
 
-// converts a list of extension structs to string
+/// 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()))
@@ -59,7 +59,7 @@ fn merge_extensions(ext: impl ToString, exts: Vec<FileExtension>) -> String {
         .join(".")
 }
 
-// create random nested directories and files under the specified directory
+/// 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;
@@ -81,7 +81,7 @@ fn create_random_files(dir: impl Into<PathBuf>, depth: u8, rng: &mut SmallRng) {
     }
 }
 
-// compress and decompress a single empty file
+/// Compress and decompress a single empty file
 #[proptest(cases = 200)]
 fn single_empty_file(ext: Extension, #[any(size_range(0..8).lift())] exts: Vec<FileExtension>) {
     let dir = tempdir().unwrap();
@@ -100,7 +100,7 @@ fn single_empty_file(ext: Extension, #[any(size_range(0..8).lift())] exts: Vec<F
     assert_same_directory(before, after, false);
 }
 
-// compress and decompress a single file
+/// Compress and decompress a single file
 #[proptest(cases = 250)]
 fn single_file(
     ext: Extension,
@@ -128,10 +128,10 @@ fn single_file(
     assert_same_directory(before, after, false);
 }
 
-// compress and decompress a directory with random content generated with create_random_files
+/// Compress and decompress a directory with random content generated with create_random_files
-//
+///
-// this one runs only 50 times because there are only `.zip` and `.tar` to be tested, and
+/// This one runs only 50 times because there are only `.zip` and `.tar` to be tested, and
-// single-file formats testing is done in the other test
+/// single-file formats testing is done in the other test
 #[proptest(cases = 50)]
 fn multiple_files(
     ext: DirectoryExtension,

tests/utils.rs

@@ -11,7 +11,7 @@ use assert_cmd::Command;
 use fs_err as fs;
 use rand::{Rng, RngCore};
 
-// Run ouch with the provided arguments, returns `assert_cmd::Output`
+/// Run ouch with the provided arguments, returns [`assert_cmd::Output`]
 #[macro_export]
 macro_rules! ouch {
     ($($e:expr),*) => {
@@ -49,15 +49,15 @@ pub fn create_files_in(dir: &Path, files: &[&str]) {
     } 
  }
 
-// write random content to a file
+/// Write random content to a file
 pub fn write_random_content(file: &mut impl Write, rng: &mut impl RngCore) {
     let mut data = vec![0; rng.gen_range(0..4096)];
     rng.fill_bytes(&mut data);
     file.write_all(&data).unwrap();
 }
 
-// check that two directories have the exact same content recursively
+/// Check that two directories have the exact same content recursively.
-// checks equility of file types if preserve_permissions is true, ignored on non-unix
+/// Checks equility of file types if preserve_permissions is true, ignored on non-unix
 // Silence clippy warning that triggers because of the `#[cfg(unix)]` on Windows.
 #[allow(clippy::only_used_in_recursion)]
 pub fn assert_same_directory(x: impl Into<PathBuf>, y: impl Into<PathBuf>, preserve_permissions: bool) {