docs: document src/services/types.rs, src/modes/common.rs, and src/services/error.rs

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

src/modes/common.rs

@@ -26,17 +26,25 @@ use std::io::IsTerminal;
 use std::str::FromStr;
 use strum::IntoEnumIterator;
 
+#[derive(Debug, Clone, strum::EnumString, strum::Display, PartialEq)]
+#[strum(ascii_case_insensitive)]
 /// Enum representing supported output formats for structured data.
 ///
-/// Used to determine how to display lists, info, and status information.
+/// Used to determine how to display lists, info, and status information in CLI modes.
+/// Defaults to Table for human-readable output; JSON/YAML for machine parsing.
 ///
 /// # 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)]
+///
+/// # Examples
+///
+/// ```
+/// use keep::modes::common::OutputFormat;
+/// assert_eq!(OutputFormat::from_str("json").unwrap(), OutputFormat::Json);
+/// ```
 pub enum OutputFormat {
     Table,
     Json,
@@ -46,16 +54,21 @@ pub enum OutputFormat {
 /// Extracts metadata from KEEP_META_* environment variables.
 ///
 /// Scans environment for variables prefixed with KEEP_META_ and extracts
-/// key-value pairs for initial item metadata.
+/// key-value pairs for initial item metadata. Ignores KEEP_META_PLUGINS.
 ///
 /// # Returns
 ///
-/// `HashMap<String, String>` - Metadata from environment variables.
+/// `HashMap<String, String>` - Metadata from environment variables, with keys in uppercase without prefix.
+///
+/// # Errors
+///
+/// None; silently ignores non-matching vars and PLUGINS.
 ///
 /// # Examples
 ///
 /// ```
 /// # use std::env;
+/// # use std::collections::HashMap;
 /// env::set_var("KEEP_META_COMMAND", "ls -la");
 /// let meta = get_meta_from_env();
 /// assert_eq!(meta.get("COMMAND"), Some(&"ls -la".to_string()));
@@ -79,14 +92,16 @@ pub fn get_meta_from_env() -> HashMap<String, String> {
 
 /// Formats a file size in bytes to human-readable or raw format.
 ///
+/// Uses the humansize crate for human-readable output with decimal units (KB, MB, etc.).
+///
 /// # Arguments
 ///
-/// * `size` - Size in bytes.
-/// * `human_readable` - If true, use units like KB, MB; otherwise, raw bytes.
+/// * `size` - Size in bytes as u64.
+/// * `human_readable` - If true, use units like KB, MB; otherwise, raw bytes as string.
 ///
 /// # Returns
 ///
-/// `String` - Formatted size string.
+/// `String` - Formatted size string, e.g., "1.0K" or "1024".
 ///
 /// # Examples
 ///
@@ -101,9 +116,11 @@ pub fn format_size(size: u64, human_readable: bool) -> String {
     }
 }
 
+#[derive(Debug, Eq, PartialEq, Clone, strum::EnumIter, strum::Display, strum::EnumString)]
+#[strum(ascii_case_insensitive)]
 /// Enum representing column types for table display.
 ///
-/// Defines standard and meta columns for list/info modes.
+/// Defines standard and meta columns for list/info modes. Supports "meta:<name>" for specific metadata columns.
 ///
 /// # Variants
 ///
@@ -115,8 +132,14 @@ pub fn format_size(size: u64, human_readable: bool) -> String {
 /// * `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)]
+///
+/// # Examples
+///
+/// ```
+/// use keep::modes::common::ColumnType;
+/// assert_eq!(ColumnType::from_str("id").unwrap(), ColumnType::Id);
+/// assert_eq!(ColumnType::from_str("meta:hostname").unwrap(), ColumnType::Meta);
+/// ```
 pub enum ColumnType {
     Id,
     Time,
@@ -131,18 +154,22 @@ pub enum ColumnType {
 impl ColumnType {
     /// Parses a string to a ColumnType, handling "meta:<name>" pattern.
     ///
+    /// Supports direct enum variants or "meta:<name>" for metadata columns.
+    ///
     /// # Arguments
     ///
-    /// * `s` - Input string to parse.
+    /// * `s` - Input string to parse, e.g., "size" or "meta:hostname".
     ///
     /// # Returns
     ///
-    /// * `anyhow::Result<ColumnType>` - Parsed type or error.
+    /// * `Ok(ColumnType)` - Parsed type on success.
+    /// * `Err(anyhow::Error)` - If the string doesn't match any variant.
     ///
     /// # Examples
     ///
     /// ```
-    /// let meta = ColumnType::from_str("meta:hostname")?;
+    /// use keep::modes::common::ColumnType;
+    /// let meta = ColumnType::from_str("meta:hostname").unwrap();
     /// assert_eq!(meta, ColumnType::Meta);
     /// ```
     pub fn from_str(s: &str) -> anyhow::Result<Self> {
@@ -244,15 +271,22 @@ pub fn settings_compression_type(cmd: &mut Command, settings: &config::Settings)
 
 /// Parses output format from settings.
 ///
-/// Defaults to `Table` if not specified or invalid.
+/// Defaults to `Table` if not specified or invalid. Uses case-insensitive string parsing.
 ///
 /// # Arguments
 ///
-/// * `settings` - Application settings.
+/// * `settings` - Application settings with optional output_format field.
 ///
 /// # Returns
 ///
-/// `OutputFormat` - Parsed or default format.
+/// `OutputFormat` - Parsed enum variant or Table as default.
+///
+/// # Examples
+///
+/// ```
+/// let format = settings_output_format(&settings);
+/// assert_eq!(format, OutputFormat::Json); // If settings.output_format = Some("json")
+/// ```
 pub fn settings_output_format(settings: &config::Settings) -> OutputFormat {
     settings.output_format
         .as_ref()
@@ -262,15 +296,15 @@ pub fn settings_output_format(settings: &config::Settings) -> OutputFormat {
 
 /// Trims trailing whitespace from each line in a multi-line string.
 ///
-/// Useful for cleaning up table output before printing.
+/// Useful for cleaning up table output before printing. Preserves newlines but removes spaces/tabs at line ends.
 ///
 /// # Arguments
 ///
-/// * `s` - Input string with potential trailing whitespace.
+/// * `s` - Input string with potential trailing whitespace, e.g., "line1  \nline2   ".
 ///
 /// # Returns
 ///
-/// `String` - Cleaned string with trimmed lines.
+/// `String` - Cleaned string with trimmed lines, e.g., "line1\nline2".
 ///
 /// # Examples
 ///