From 93d99a644ad83054f5d89c0cd84ee9dcc93e2543 Mon Sep 17 00:00:00 2001
From: Andrew Phillips <andrew.phillips2@canada.ca>
Date: Wed, 10 Sep 2025 11:14:03 -0300
Subject: [PATCH] docs: add rustdoc to compression_engine module

Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) <aider@aider.chat>
---
 src/compression_engine.rs | 69 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/src/compression_engine.rs b/src/compression_engine.rs
index 401c2a4..142bdc8 100755
--- a/src/compression_engine.rs
+++ b/src/compression_engine.rs
@@ -22,6 +22,7 @@ use crate::compression_engine::lz4::CompressionEngineLZ4;
 use crate::compression_engine::none::CompressionEngineNone;
 use crate::compression_engine::program::CompressionEngineProgram;
 
+/// Enum representing different compression types supported by the system
 #[derive(Debug, Eq, PartialEq, Clone, strum::EnumIter, strum::Display, strum::EnumString, Enum)]
 #[strum(ascii_case_insensitive)]
 pub enum CompressionType {
@@ -33,14 +34,49 @@ pub enum CompressionType {
     None,
 }
 
+/// Trait defining the interface for compression engines
 pub trait CompressionEngine {
+    /// Opens a compressed file for reading
+    ///
+    /// # Arguments
+    ///
+    /// * `file_path` - Path to the compressed file
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Box<dyn Read>>` - A boxed reader that decompresses the file on read
     fn open(&self, file_path: PathBuf) -> Result<Box<dyn Read>>;
+    
+    /// Creates a new compressed file for writing
+    ///
+    /// # Arguments
+    ///
+    /// * `file_path` - Path where the compressed file will be created
+    ///
+    /// # Returns
+    ///
+    /// * `Result<Box<dyn Write>>` - A boxed writer that compresses data on write
     fn create(&self, file_path: PathBuf) -> Result<Box<dyn Write>>;
 
+    /// Checks if this compression engine is supported on the current system
+    ///
+    /// # Returns
+    ///
+    /// * `bool` - True if supported, false otherwise
     fn is_supported(&self) -> bool {
         true
     }
 
+    /// Copies decompressed content from a file to a writer
+    ///
+    /// # Arguments
+    ///
+    /// * `file_path` - Path to the compressed file
+    /// * `writer` - Writer to receive decompressed content
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - Success or error
     fn copy(&self, file_path: PathBuf, writer: &mut dyn Write) -> Result<()> {
         let mut reader = self.open(file_path)?;
         io::copy(&mut reader, writer)?;
@@ -48,11 +84,29 @@ pub trait CompressionEngine {
         Ok(())
     }
 
+    /// Decompresses and outputs file content to stdout
+    ///
+    /// # Arguments
+    ///
+    /// * `file_path` - Path to the compressed file
+    ///
+    /// # Returns
+    ///
+    /// * `Result<()>` - Success or error
     fn cat(&self, file_path: PathBuf) -> Result<()> {
         let mut stdout = io::stdout().lock();
         self.copy(file_path, &mut stdout)
     }
 
+    /// Calculates the decompressed size of a file
+    ///
+    /// # Arguments
+    ///
+    /// * `file_path` - Path to the compressed file
+    ///
+    /// # Returns
+    ///
+    /// * `Result<usize>` - The decompressed size in bytes
     fn size(&self, file_path: PathBuf) -> Result<usize> {
         let mut reader = self.open(file_path)?;
         let mut buffer = [0; libc::BUFSIZ as usize];
@@ -73,6 +127,7 @@ pub trait CompressionEngine {
 }
 
 lazy_static! {
+    /// Mapping of compression types to their external program implementations
     pub static ref COMPRESSION_PROGRAMS: EnumMap<CompressionType, Option<CompressionEngineProgram>> = enum_map! {
         CompressionType::LZ4 => {
             let program = CompressionEngineProgram::new("lz4", vec!["-c"], vec!["-d", "-c"]);
@@ -104,6 +159,15 @@ lazy_static! {
     };
 }
 
+/// Gets a compression engine for the specified compression type
+///
+/// # Arguments
+///
+/// * `compression_type` - The type of compression to use
+///
+/// # Returns
+///
+/// * `Result<Box<dyn CompressionEngine>>` - A boxed compression engine instance
 pub fn get_compression_engine(
     compression_type: CompressionType,
 ) -> Result<Box<dyn CompressionEngine>> {
@@ -148,6 +212,11 @@ pub fn get_compression_engine(
     }
 }
 
+/// Gets the default compression type based on available support
+///
+/// # Returns
+///
+/// * `CompressionType` - The first supported compression type found
 pub fn default_compression_type() -> CompressionType {
     let mut default = CompressionType::None;
     for compression_type in CompressionType::iter() {