docs: Add Rustdoc examples to server common types and compression engine

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

src/compression_engine/gzip.rs

@@ -1,8 +1,18 @@
+```rust
 /// 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.
+///
+/// # Usage
+///
+/// ```rust
+/// use keep::compression_engine::get_compression_engine;
+/// let engine = get_compression_engine(keep::compression_engine::CompressionType::GZip)
+///     .expect("GZip engine creation failed");
+/// let reader = engine.open("/path/to/file.gz".into()).expect("Open failed");
+/// ```
 use anyhow::Result;
 use log::*;
 use std::fs::File;
@@ -16,11 +26,20 @@ use flate2::write::GzEncoder;
 
 use crate::compression_engine::CompressionEngine;
 
+```rust
 /// 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.
+///
+/// # Examples
+///
+/// ```rust
+/// let engine = keep::compression_engine::get_compression_engine(keep::compression_engine::CompressionType::GZip)
+///     .expect("Failed to get GZip engine");
+/// assert!(engine.is_supported());
+/// ```
 #[derive(Debug, Eq, PartialEq, Clone, Default)]
 pub struct CompressionEngineGZip {}
 
@@ -30,6 +49,12 @@ impl CompressionEngineGZip {
     /// # Returns
     ///
     /// A new `CompressionEngineGZip` instance.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let engine = CompressionEngineGZip::new();
+    /// ```
     pub fn new() -> CompressionEngineGZip {
         CompressionEngineGZip {}
     }
@@ -44,6 +69,13 @@ impl CompressionEngine for CompressionEngineGZip {
     /// # Returns
     ///
     /// Always returns `true` since GZip is built-in.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let engine = CompressionEngineGZip::new();
+    /// assert!(engine.is_supported());
+    /// ```
     fn is_supported(&self) -> bool {
         true
     }
@@ -60,6 +92,16 @@ impl CompressionEngine for CompressionEngineGZip {
     /// # Returns
     ///
     /// * `Result<Box<dyn Read>>` - A boxed reader that decompresses the GZip file on read.
+    ///
+    /// # Errors
+    ///
+    /// * `anyhow::Error` - If the file cannot be opened or decoded.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let reader = engine.open("/path/to/file.gz".into()).expect("Open failed");
+    /// ```
     fn open(&self, file_path: PathBuf) -> Result<Box<dyn Read>> {
         debug!("COMPRESSION: Opening {:?} using {:?}", file_path, *self);
 
@@ -80,6 +122,16 @@ impl CompressionEngine for CompressionEngineGZip {
     /// # Returns
     ///
     /// * `Result<Box<dyn Write>>` - A boxed writer that compresses data using GZip on write.
+    ///
+    /// # Errors
+    ///
+    /// * `anyhow::Error` - If the file cannot be created or encoder fails.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let writer = engine.create("/path/to/file.gz".into()).expect("Create failed");
+    /// ```
     fn create(&self, file_path: PathBuf) -> Result<Box<dyn Write>> {
         debug!("COMPRESSION: Writting to {:?} using {:?}", file_path, *self);
 
@@ -90,10 +142,20 @@ impl CompressionEngine for CompressionEngineGZip {
     }
 }
 
+```rust
 /// Auto-finishing GZip encoder that automatically calls finish on drop.
 ///
 /// This wrapper ensures that the GZip stream is properly closed even if the
 /// writer is dropped unexpectedly, preventing incomplete compression files.
+///
+/// # Examples
+///
+/// ```rust
+/// let file = File::create("test.gz").unwrap();
+/// let encoder = GzEncoder::new(file, Compression::default());
+/// let auto_encoder = AutoFinishGzEncoder::new(encoder);
+/// // Encoder will finish on drop
+/// ```
 pub struct AutoFinishGzEncoder<W: Write> {
     encoder: Option<GzEncoder<W>>,
 }
@@ -108,6 +170,14 @@ impl<W: Write> AutoFinishGzEncoder<W> {
     /// # Returns
     ///
     /// A new `AutoFinishGzEncoder` instance.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let file = File::create("test.gz").unwrap();
+    /// let encoder = GzEncoder::new(file, Compression::default());
+    /// let auto_encoder = AutoFinishGzEncoder::new(encoder);
+    /// ```
     fn new(gz_encoder: GzEncoder<W>) -> AutoFinishGzEncoder<W> {
         AutoFinishGzEncoder {
             encoder: Some(gz_encoder),
@@ -120,6 +190,10 @@ impl<W: Write> Drop for AutoFinishGzEncoder<W> {
     ///
     /// This method ensures the GZip stream is properly closed by calling `finish()`
     /// on the underlying encoder.
+    ///
+    /// # Errors
+    ///
+    /// Errors during finish are logged but ignored.
     fn drop(&mut self) {
         if let Some(encoder) = self.encoder.take() {
             debug!("COMPRESSION: Finishing");
@@ -138,6 +212,10 @@ impl<W: Write> Write for AutoFinishGzEncoder<W> {
     /// # Returns
     ///
     /// * `io::Result<usize>` - The number of bytes written or an I/O error.
+    ///
+    /// # Errors
+    ///
+    /// Propagates errors from the underlying encoder.
     fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
         self.encoder.as_mut().unwrap().write(buf)
     }
@@ -147,6 +225,10 @@ impl<W: Write> Write for AutoFinishGzEncoder<W> {
     /// # Returns
     ///
     /// * `io::Result<()>` - Success or an I/O error.
+    ///
+    /// # Errors
+    ///
+    /// Propagates errors from the underlying encoder.
     fn flush(&mut self) -> io::Result<()> {
         self.encoder.as_mut().unwrap().flush()
     }