docs: Add comprehensive rustdoc for meta_plugin/magic.rs, and update PLAN.md

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

PLAN.md

@@ -91,30 +91,30 @@ Private helpers (e.g., internal `fn` without `pub`) are not flagged, as they don
     - Impl `MetaPlugin` methods: No docs.
     - Overall: Complex logic with no rustdoc.
 
-11. **src/compression_engine/program.rs**
+11. **src/compression_engine/program.rs** [DONE]
     - `ProgramReader` and `ProgramWriter` structs: Partial (missing full impl docs).
     - `CompressionEngineProgram` struct: Partial.
     - `new()` function: Partial.
     - Impl `CompressionEngine` methods: Partial.
     - Overall: Good but incomplete for trait methods.
 
-12. **src/meta_plugin/read_time.rs**
+12. **src/meta_plugin/read_time.rs** [DONE]
     - `ReadTimeMetaPlugin` struct: No doc.
     - `new()` function: Partial.
     - Impl `MetaPlugin` methods: No docs.
     - Overall: Similar to read_rate.rs.
 
-13. **src/modes/server/api/common.rs**
+13. **src/modes/server/api/common.rs** [DONE]
     - `ResponseBuilder` struct: No doc.
     - `json()` and `binary()` methods: No docs.
     - Overall: Utility without docs.
 
-14. **src/compression_engine/lz4.rs**
+14. **src/compression_engine/lz4.rs** [DONE]
     - `CompressionEngineLZ4` struct: No doc.
     - `new()` function: No doc.
     - Impl `CompressionEngine` methods: No docs.
 
-15. **src/meta_plugin/magic.rs** (appears to be a duplicate/old version of magic_file.rs)
+15. **src/meta_plugin/magic.rs** [DONE]
     - `MagicFileMetaPlugin` struct: No doc.
     - `new()` function: Partial.
     - Helper functions (`get_magic_result`, `process_magic_types`): No docs.

src/meta_plugin/magic.rs

@@ -121,14 +121,42 @@ impl MagicFileMetaPlugin {
 }
 
 impl MetaPlugin for MagicFileMetaPlugin {
+    /// Checks if the plugin has been finalized.
+    ///
+    /// # Returns
+    ///
+    /// `true` if finalized, `false` otherwise.
     fn is_finalized(&self) -> bool {
         self.is_finalized
     }
     
+    /// Sets the finalized state of the plugin.
+    ///
+    /// # Arguments
+    ///
+    /// * `finalized` - The new finalized state.
     fn set_finalized(&mut self, finalized: bool) {
         self.is_finalized = finalized;
     }
     
+    /// Initializes the magic cookie for file type detection.
+    ///
+    /// Loads the magic database; finalizes if initialization fails.
+    ///
+    /// # Returns
+    ///
+    /// A `MetaPluginResponse` with empty metadata; `is_finalized` is `true` on failure.
+    ///
+    /// # Errors
+    ///
+    /// Logs errors; returns finalized response on cookie or load failure.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut plugin = MagicFileMetaPlugin::new(None, None);
+    /// let response = plugin.initialize();
+    /// ```
     fn initialize(&mut self) -> crate::meta_plugin::MetaPluginResponse {
         // Initialize the magic cookie once
         let cookie = match Cookie::open(Default::default()) {
@@ -154,6 +182,22 @@ impl MetaPlugin for MagicFileMetaPlugin {
         }
     }
 
+    /// Finalizes the plugin and performs file type detection.
+    ///
+    /// Analyzes the accumulated buffer and outputs detected types.
+    ///
+    /// # Returns
+    ///
+    /// A `MetaPluginResponse` with detection metadata and finalized state set to `true`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut plugin = MagicFileMetaPlugin::new(None, None);
+    /// // ... after updates
+    /// let response = plugin.finalize();
+    /// assert!(response.is_finalized);
+    /// ```
     fn finalize(&mut self) -> crate::meta_plugin::MetaPluginResponse {
         // If already finalized, don't process again
         if self.is_finalized {
@@ -174,6 +218,24 @@ impl MetaPlugin for MagicFileMetaPlugin {
         }
     }
 
+    /// Updates the plugin with new data, accumulating for analysis.
+    ///
+    /// Buffers data up to `max_buffer_size`; triggers detection when full.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - Content chunk to buffer.
+    ///
+    /// # Returns
+    ///
+    /// A `MetaPluginResponse` with metadata on buffer full; finalizes then.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut plugin = MagicFileMetaPlugin::new(None, None);
+    /// let response = plugin.update(b"content");
+    /// ```
     fn update(&mut self, data: &[u8]) -> crate::meta_plugin::MetaPluginResponse {
         // If already finalized, don't process more data
         if self.is_finalized {
@@ -207,32 +269,63 @@ impl MetaPlugin for MagicFileMetaPlugin {
         }
     }
 
+    /// Returns the type of this meta plugin.
+    ///
+    /// # Returns
+    ///
+    /// `MetaPluginType::MagicFile`.
     fn meta_type(&self) -> MetaPluginType {
         MetaPluginType::MagicFile
     }
     
     
+    /// Returns a reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the `HashMap` of outputs.
     fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         self.base.outputs()
     }
     
+    /// Returns a mutable reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the `HashMap` of outputs.
     fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         self.base.outputs_mut()
     }
     
+    /// Returns the default output names for this plugin.
+    ///
+    /// # Returns
+    ///
+    /// Vector of default output field names.
     fn default_outputs(&self) -> Vec<String> {
         vec!["mime_type".to_string(), "mime_encoding".to_string(), "file_type".to_string()]
     }
     
     
+    /// Returns a reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the `HashMap` of options.
     fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         self.base.options()
     }
     
+    /// Returns a mutable reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the `HashMap` of options.
     fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         self.base.options_mut()
     }
 }
+}
 
 use crate::meta_plugin::register_meta_plugin;