From a7bcad40bb7775f1205f2d0bf919ab0020695a2e Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Wed, 10 Sep 2025 12:53:21 -0300 Subject: [PATCH] docs: Add comprehensive rustdoc to common module functions Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) --- src/modes/common.rs | 201 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 187 insertions(+), 14 deletions(-) diff --git a/src/modes/common.rs b/src/modes/common.rs index a927695..0fc868b 100644 --- a/src/modes/common.rs +++ b/src/modes/common.rs @@ -1,3 +1,17 @@ +/// Common utilities shared across different modes in the Keep application. +/// +/// This module provides helper functions for formatting, configuration parsing, +/// table creation, and environment variable handling used by various CLI modes. +/// +/// # Usage +/// +/// These utilities are typically used internally by mode implementations: +/// +/// ``` +/// use crate::modes::common::{format_size, OutputFormat}; +/// let formatted = format_size(1024, true); // "1.0K" +/// let format = OutputFormat::from_str("json")?; +/// ``` use crate::config; use crate::compression_engine::CompressionType; use crate::meta_plugin::MetaPluginType; @@ -11,6 +25,16 @@ use std::env; use std::io::IsTerminal; use std::str::FromStr; use strum::IntoEnumIterator; + +/// Enum representing supported output formats for structured data. +/// +/// Used to determine how to display lists, info, and status information. +/// +/// # Variants +/// +/// * `Table` - Formatted table output (default). +/// * `Json` - JSON structured output. +/// * `Yaml` - YAML structured output. #[derive(Debug, Clone, strum::EnumString, strum::Display, PartialEq)] #[strum(ascii_case_insensitive)] pub enum OutputFormat { @@ -19,6 +43,23 @@ pub enum OutputFormat { Yaml, } +/// Extracts metadata from KEEP_META_* environment variables. +/// +/// Scans environment for variables prefixed with KEEP_META_ and extracts +/// key-value pairs for initial item metadata. +/// +/// # Returns +/// +/// `HashMap` - Metadata from environment variables. +/// +/// # Examples +/// +/// ``` +/// # use std::env; +/// env::set_var("KEEP_META_COMMAND", "ls -la"); +/// let meta = get_meta_from_env(); +/// assert_eq!(meta.get("COMMAND"), Some(&"ls -la".to_string())); +/// ``` pub fn get_meta_from_env() -> HashMap { debug!("COMMON: Getting meta from KEEP_META_*"); let re = Regex::new(r"^KEEP_META_(.+)$").unwrap(); @@ -36,6 +77,23 @@ pub fn get_meta_from_env() -> HashMap { meta_env } +/// Formats a file size in bytes to human-readable or raw format. +/// +/// # Arguments +/// +/// * `size` - Size in bytes. +/// * `human_readable` - If true, use units like KB, MB; otherwise, raw bytes. +/// +/// # Returns +/// +/// `String` - Formatted size string. +/// +/// # Examples +/// +/// ``` +/// let raw = format_size(1024, false); // "1024" +/// let human = format_size(1024, true); // "1.0K" +/// ``` pub fn format_size(size: u64, human_readable: bool) -> String { match human_readable { true => humansize::format_size(size, humansize::DECIMAL), @@ -43,8 +101,20 @@ pub fn format_size(size: u64, human_readable: bool) -> String { } } - - +/// Enum representing column types for table display. +/// +/// Defines standard and meta columns for list/info modes. +/// +/// # Variants +/// +/// * `Id` - Item ID column. +/// * `Time` - Timestamp column. +/// * `Size` - Content size column. +/// * `Compression` - Compression type column. +/// * `FileSize` - On-disk file size column. +/// * `FilePath` - File path column. +/// * `Tags` - Tags column. +/// * `Meta` - Metadata column (with sub-type via string parsing). #[derive(Debug, Eq, PartialEq, Clone, strum::EnumIter, strum::Display, strum::EnumString)] #[strum(ascii_case_insensitive)] pub enum ColumnType { @@ -59,7 +129,22 @@ pub enum ColumnType { } impl ColumnType { - /// Returns a Result with error message if the string is not a valid ColumnType + /// Parses a string to a ColumnType, handling "meta:" pattern. + /// + /// # Arguments + /// + /// * `s` - Input string to parse. + /// + /// # Returns + /// + /// * `anyhow::Result` - Parsed type or error. + /// + /// # Examples + /// + /// ``` + /// let meta = ColumnType::from_str("meta:hostname")?; + /// assert_eq!(meta, ColumnType::Meta); + /// ``` pub fn from_str(s: &str) -> anyhow::Result { if s.starts_with("meta:") { // Handle meta: pattern - this is still a Meta column type @@ -71,13 +156,22 @@ impl ColumnType { } } -// impl TryFrom<&str> for ColumnType is already implemented by strum_macros -// so we remove this conflicting implementation - - - - - +/// Extracts configured meta plugin types from settings and command. +/// +/// Handles comma-separated plugin names and validates against registered types. +/// +/// # Arguments +/// +/// * `cmd` - Mutable Clap command for error reporting. +/// * `settings` - Application settings with plugin config. +/// +/// # Returns +/// +/// `Vec` - List of enabled plugin types. +/// +/// # Panics +/// +/// Exits via Clap error if unknown plugin type specified. pub fn settings_meta_plugin_types(cmd: &mut Command, settings: &config::Settings) -> Vec { let mut meta_plugin_types = Vec::new(); @@ -115,7 +209,22 @@ pub fn settings_meta_plugin_types(cmd: &mut Command, settings: &config::Settings meta_plugin_types } - +/// Determines compression type from settings and command arguments. +/// +/// Validates the compression name and returns the corresponding enum variant. +/// +/// # Arguments +/// +/// * `cmd` - Mutable Clap command for error reporting. +/// * `settings` - Application settings. +/// +/// # Returns +/// +/// `CompressionType` - The resolved compression type. +/// +/// # Panics +/// +/// Exits via Clap error if invalid compression specified. pub fn settings_compression_type(cmd: &mut Command, settings: &config::Settings) -> CompressionType { let compression_name = settings .compression() @@ -133,6 +242,17 @@ pub fn settings_compression_type(cmd: &mut Command, settings: &config::Settings) compression_type_opt.unwrap() } +/// Parses output format from settings. +/// +/// Defaults to `Table` if not specified or invalid. +/// +/// # Arguments +/// +/// * `settings` - Application settings. +/// +/// # Returns +/// +/// `OutputFormat` - Parsed or default format. pub fn settings_output_format(settings: &config::Settings) -> OutputFormat { settings.output_format .as_ref() @@ -140,7 +260,24 @@ pub fn settings_output_format(settings: &config::Settings) -> OutputFormat { .unwrap_or(OutputFormat::Table) } -/// Trim whitespace from the end of each line in a string +/// Trims trailing whitespace from each line in a multi-line string. +/// +/// Useful for cleaning up table output before printing. +/// +/// # Arguments +/// +/// * `s` - Input string with potential trailing whitespace. +/// +/// # Returns +/// +/// `String` - Cleaned string with trimmed lines. +/// +/// # Examples +/// +/// ``` +/// let cleaned = trim_lines_end("line1 \nline2 "); +/// assert_eq!(cleaned, "line1\nline2"); +/// ``` pub fn trim_lines_end(s: &str) -> String { s.lines() .map(|line| line.trim_end()) @@ -148,7 +285,24 @@ pub fn trim_lines_end(s: &str) -> String { .join("\n") } -/// Create a table with consistent styling and terminal detection +/// Creates a new table with styling based on terminal detection. +/// +/// Loads appropriate preset (UTF8 or ASCII) if styling is enabled. +/// +/// # Arguments +/// +/// * `use_styling` - If true, apply visual styling. +/// +/// # Returns +/// +/// `Table` - Configured table instance. +/// +/// # Examples +/// +/// ``` +/// let table = create_table(true); +/// table.add_row(vec!["Header1", "Header2"]); +/// ``` pub fn create_table(use_styling: bool) -> Table { let mut table = Table::new(); table.set_content_arrangement(ContentArrangement::Dynamic); @@ -171,7 +325,24 @@ pub fn create_table(use_styling: bool) -> Table { table } -/// Create a table using the provided table configuration +/// Creates a table configured from application table settings. +/// +/// Applies style presets, modifiers, content arrangement, and truncation indicators. +/// +/// # Arguments +/// +/// * `table_config` - Table configuration from settings. +/// +/// # Returns +/// +/// `Table` - Fully configured table. +/// +/// # Examples +/// +/// ``` +/// let config = TableConfig::default(); +/// let table = create_table_with_config(&config); +/// ``` pub fn create_table_with_config(table_config: &crate::config::TableConfig) -> Table { let mut table = Table::new(); @@ -235,3 +406,5 @@ pub fn create_table_with_config(table_config: &crate::config::TableConfig) -> Ta table } +/// Exports public types and functions for use in other modules. +pub use self::{ColumnType, OutputFormat, format_size, settings_output_format};