docs: Add rustdoc to all files, document arguments and returns

Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>

src/compression_engine/gzip.rs

@@ -1,3 +1,8 @@
+/// GZip compression engine module.
+///
+/// This module provides the implementation for GZip compression and decompression
+/// using the `flate2` crate. It includes the main `CompressionEngineGZip` struct
+/// and supporting types for handling GZip streams.
 use anyhow::Result;
 use log::*;
 use std::fs::File;
@@ -11,7 +16,11 @@ use flate2::write::GzEncoder;
 
 use crate::compression_engine::CompressionEngine;
 
-/// GZip compression engine implementation
+/// GZip compression engine implementation.
+///
+/// This struct provides the functionality to compress and decompress data using
+/// the GZip algorithm. It implements the `CompressionEngine` trait for integration
+/// with the compression service.
 #[derive(Debug, Eq, PartialEq, Clone, Default)]
 pub struct CompressionEngineGZip {}
 
@@ -29,6 +38,9 @@ impl CompressionEngineGZip {
 impl CompressionEngine for CompressionEngineGZip {
     /// Checks if GZip compression is supported.
     ///
+    /// GZip is a built-in compression method using the `flate2` crate, so it is
+    /// always supported.
+    ///
     /// # Returns
     ///
     /// Always returns `true` since GZip is built-in.
@@ -38,6 +50,9 @@ impl CompressionEngine for CompressionEngineGZip {
 
     /// Opens a GZip compressed file for reading.
     ///
+    /// This method creates a `GzDecoder` wrapped around the file, allowing the
+    /// file to be read as if it were uncompressed.
+    ///
     /// # Arguments
     ///
     /// * `file_path` - Path to the GZip compressed file.
@@ -54,6 +69,10 @@ impl CompressionEngine for CompressionEngineGZip {
 
     /// Creates a new GZip compressed file for writing.
     ///
+    /// This method creates a file and wraps it in a `GzEncoder` with default
+    /// compression settings. It uses `AutoFinishGzEncoder` to ensure the GZip
+    /// stream is properly closed on drop.
+    ///
     /// # Arguments
     ///
     /// * `file_path` - Path where the GZip compressed file will be created.
@@ -73,7 +92,8 @@ impl CompressionEngine for CompressionEngineGZip {
 
 /// Auto-finishing GZip encoder that automatically calls finish on drop.
 ///
-/// This ensures the GZip stream is properly closed even if the writer is dropped unexpectedly.
+/// This wrapper ensures that the GZip stream is properly closed even if the
+/// writer is dropped unexpectedly, preventing incomplete compression files.
 pub struct AutoFinishGzEncoder<W: Write> {
     encoder: Option<GzEncoder<W>>,
 }
@@ -97,6 +117,9 @@ impl<W: Write> AutoFinishGzEncoder<W> {
 
 impl<W: Write> Drop for AutoFinishGzEncoder<W> {
     /// Automatically finishes the GZip encoding when the writer is dropped.
+    ///
+    /// This method ensures the GZip stream is properly closed by calling `finish()`
+    /// on the underlying encoder.
     fn drop(&mut self) {
         if let Some(encoder) = self.encoder.take() {
             debug!("COMPRESSION: Finishing");