docs: documentation cleanup

README.md

@@ -10,6 +10,9 @@ cargo install oliframe
 ```
 
 ### For library usage
+While the purpose of this project is to provide a command-line tool,
+the underlying library can be used in other projects.
+
 Add the following to your `Cargo.toml` file:
 ```toml
 [dependencies]

src/args.rs

@@ -1,3 +1,6 @@
+//! Command line argument parsing
+//!
+//! This module defines the Args struct, which is used to parse command line arguments.
 use clap::Parser;
 use csscolorparser::Color;
 use std::path::PathBuf;

src/file_collector.rs

@@ -1,3 +1,8 @@
+//! # FileCollector
+//!
+//! This module contains the FileCollector struct, which is responsible for collecting a list of files
+//! to be processed by the program.
+
 use crate::args::Args;
 use crate::image_file::ImageFile;
 use junk_file::is_not_junk;
@@ -70,6 +75,7 @@ impl FileCollector {
     }
 }
 
+// Checks if a file exists, and if it does, prompts the user to confirm overwriting it.
 fn validate_overwrite(output_path: &Path) -> OverwriteResult {
     match output_path.try_exists() {
         Ok(true) => {
@@ -105,17 +111,17 @@ fn validate_overwrite(output_path: &Path) -> OverwriteResult {
     }
 }
 
-/// Returns a list of input files
-///
-/// This function will return a list of input files based on the following rules:
-///
-/// 1. If the `--dir` option is specified, all files in that directory will be returned.
-/// 2. If the `--file` option is specified, all files specified will be returned.
-/// 3. If both `--dir` and `--file` are specified, all files in the directory will be returned, and all files specified will be returned.
-/// 4. If neither `--dir` nor `--file` are specified, all files in the current directory will be returned.
-/// 5. If the `--extension` option is specified,
-///     only files with the specified extension(s) will be returned.
-/// 6. The `junk_file` crate is used to filter out OS-specific junk files.
+// Returns a list of input files
+//
+// This function will return a list of input files based on the following rules:
+//
+// 1. If the `--dir` option is specified, all files in that directory will be returned.
+// 2. If the `--file` option is specified, all files specified will be returned.
+// 3. If both `--dir` and `--file` are specified, all files in the directory will be returned, and all files specified will be returned.
+// 4. If neither `--dir` nor `--file` are specified, all files in the current directory will be returned.
+// 5. If the `--extension` option is specified,
+//     only files with the specified extension(s) will be returned.
+// 6. The `junk_file` crate is used to filter out OS-specific junk files.
 fn input_files(args: &Args) -> Vec<PathBuf> {
     let mut files: Vec<PathBuf> = Vec::new();
 
@@ -149,7 +155,7 @@ fn input_files(args: &Args) -> Vec<PathBuf> {
     files
 }
 
-/// Given a path, returns a list of files in that path that match the specified extension(s)
+// Given a path, returns a list of files in that path that match the specified extension(s)
 fn extract_files(args: &Args, path: &PathBuf, depth: u8) -> Vec<PathBuf> {
     let mut files = Vec::new();
 
@@ -185,15 +191,15 @@ fn extract_files(args: &Args, path: &PathBuf, depth: u8) -> Vec<PathBuf> {
     files
 }
 
-/// Returns true if the given path's extension matches one of the specified extensions.
+// Returns true if the given path's extension matches one of the specified extensions.
 fn has_specified_extension(args: &Args, path: &Path) -> bool {
     match path.extension() {
         Some(path_ext) => args.extension.iter().any(|ext| path_ext == OsStr::new(ext)),
         None => false,
     }
 }
 
-/// Returns the output path for the given input path
+// Returns the output path for the given input path
 fn output_path(args: &Args, input_path: &Path) -> Result<PathBuf, FileCollectorError> {
     let mut output_path = PathBuf::new();
     let extension = input_path.extension().unwrap_or(OsStr::new(""));

src/image_file.rs

@@ -1,8 +1,13 @@
+//! ImageFile struct and methods
+//!
+//! The ImageFile struct represents a single image file that will be processed by the program.
+
 use crate::args::Args;
 use oliframe::{add_border, BorderWidth};
 use std::fmt::Display;
 use std::path::PathBuf;
 
+/// Represents a single image file that will be processed by the program
 pub struct ImageFile {
     input_path: PathBuf,
     output_path: PathBuf,
@@ -15,13 +20,15 @@ impl Display for ImageFile {
 }
 
 impl ImageFile {
+    /// Creates a new ImageFile instance
     pub fn new(input_path: PathBuf, output_path: PathBuf) -> Self {
         Self {
             input_path,
             output_path,
         }
     }
 
+    /// Adds a border to the image file
     pub fn add_border(&self, args: &Args) -> Result<(), String> {
         let img = image::open(&self.input_path)
             .map_err(|e| format!("Unable to open {}: {}", self.input_path.display(), e))?;

src/lib.rs

@@ -1,4 +1,7 @@
-pub use csscolorparser::Color as Color;
+#![deny(missing_docs)]
+//! Add simple borders to images using the `image` crate.
+
+pub use csscolorparser::Color;
 pub use image;
 
 use image::{DynamicImage, GenericImageView, Rgba, RgbaImage};

src/main.rs

@@ -1,3 +1,6 @@
+#![deny(missing_docs)]
+//! A simple tool to add borders to images.
+
 mod args;
 mod file_collector;
 mod image_file;