From 4c47dceef54de7e112565b06ffeff11e2886d289 Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Wed, 10 Sep 2025 14:00:43 -0300 Subject: [PATCH] docs: Add comprehensive rustdoc for meta_plugin/magic.rs, and update PLAN.md Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) --- PLAN.md | 10 ++--- src/meta_plugin/magic.rs | 93 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 5 deletions(-) diff --git a/PLAN.md b/PLAN.md index e2864e3..0221c81 100644 --- a/PLAN.md +++ b/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. diff --git a/src/meta_plugin/magic.rs b/src/meta_plugin/magic.rs index ffd0aeb..bfd329e 100644 --- a/src/meta_plugin/magic.rs +++ b/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 { 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 { self.base.outputs_mut() } + /// Returns the default output names for this plugin. + /// + /// # Returns + /// + /// Vector of default output field names. fn default_outputs(&self) -> Vec { 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 { 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 { self.base.options_mut() } } +} use crate::meta_plugin::register_meta_plugin;