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>

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;