From 58b5c8187bc9ad402dbe90dee6931cdfde2b1c5b Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Wed, 10 Sep 2025 12:28:47 -0300 Subject: [PATCH] docs: Add Rustdoc for modules, functions, and structs Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) --- src/args.rs | 27 ++++++++++----------------- src/common/mod.rs | 2 ++ src/main.rs | 1 + src/modes/delete.rs | 15 +++++++++++++++ src/modes/get.rs | 15 +++++++++++++++ src/modes/mod.rs | 24 ++++++++++++++++++++++++ src/parser/mod.rs | 1 + src/services/error.rs | 1 + 8 files changed, 69 insertions(+), 17 deletions(-) diff --git a/src/args.rs b/src/args.rs index 40e87ea..cd37b79 100644 --- a/src/args.rs +++ b/src/args.rs @@ -3,9 +3,7 @@ use std::str::FromStr; use clap::*; -/** - * Main struct for command-line arguments. - */ +/// Main struct for command-line arguments, parsed via Clap. #[derive(Parser, Debug, Clone)] #[command(author, version, about, long_about = None)] pub struct Args { @@ -22,9 +20,7 @@ pub struct Args { pub ids_or_tags: Vec, } -/** - * Struct for mode-specific arguments. - */ +/// Struct for mode-specific arguments, defining CLI flags for different operations. #[derive(Parser, Debug, Clone)] pub struct ModeArgs { #[arg(group("mode"), help_heading("Mode Options"), short, long, conflicts_with_all(["get", "diff", "list", "delete", "info", "status"]))] @@ -82,9 +78,7 @@ pub struct ModeArgs { pub server_port: Option, } -/** - * Struct for item-specific arguments. - */ +/// Struct for item-specific arguments, such as compression and plugins. #[derive(Parser, Debug, Clone)] pub struct ItemArgs { #[arg(help_heading("Item Options"), short, long, env("KEEP_COMPRESSION"))] @@ -101,9 +95,7 @@ pub struct ItemArgs { } -/** - * Struct for general options. - */ +/// Struct for general options, including verbosity, paths, and output settings. #[derive(Parser, Debug, Default, Clone)] pub struct OptionsArgs { #[arg(long, env("KEEP_CONFIG"))] @@ -150,11 +142,7 @@ pub struct OptionsArgs { pub force: bool, } -use derive_more::From; - -/** - * Enum for representing either a number or a string. - */ +/// Enum for representing either a number (item ID) or a string (tag). #[derive(Debug, Clone, From)] pub enum NumberOrString { Number(i64), @@ -170,6 +158,11 @@ impl FromStr for NumberOrString { } } +/// Validates the parsed arguments based on mode constraints. +/// +/// # Returns +/// +/// `Result<(), String>` - Ok if valid, or an error message string. impl Args { /// Validate the arguments based on the selected mode pub fn validate(&self) -> Result<(), String> { diff --git a/src/common/mod.rs b/src/common/mod.rs index ea1c08d..c43dcb7 100644 --- a/src/common/mod.rs +++ b/src/common/mod.rs @@ -1,4 +1,6 @@ pub mod is_binary; + +/// Detects if data is binary or text based on signatures and printable ratios. pub mod status; /// Standard buffer size for I/O operations (8KB) diff --git a/src/main.rs b/src/main.rs index a1100b7..1303191 100644 --- a/src/main.rs +++ b/src/main.rs @@ -81,6 +81,7 @@ fn main() -> Result<(), Error> { tags.sort(); tags.dedup(); + /// Internal enum representing the parsed execution mode. #[derive(PartialEq, Debug)] enum KeepModes { Unknown, diff --git a/src/modes/delete.rs b/src/modes/delete.rs index 3a2beb7..1e07e53 100644 --- a/src/modes/delete.rs +++ b/src/modes/delete.rs @@ -8,6 +8,21 @@ use clap::Command; use log::warn; use rusqlite::Connection; +/// Handles the delete mode: removes items by ID from the database and storage. +/// +/// # Arguments +/// +/// * `_cmd` - Clap command for error handling (unused). +/// * `_settings` - Global settings (unused). +/// * `_config` - Configuration settings (unused). +/// * `ids` - List of item IDs to delete. +/// * `_tags` - Tags (unused, as delete only supports IDs). +/// * `conn` - Database connection. +/// * `data_path` - Path to data directory for storage cleanup. +/// +/// # Returns +/// +/// `Result<()>` on success, or an error if deletion fails. pub fn mode_delete( _cmd: &mut Command, _settings: &config::Settings, diff --git a/src/modes/get.rs b/src/modes/get.rs index 8af949b..b5b0c0b 100644 --- a/src/modes/get.rs +++ b/src/modes/get.rs @@ -11,6 +11,21 @@ use is_terminal::IsTerminal; use std::path::PathBuf; use std::io::Read; +/// Handles the get mode: retrieves and streams item content to stdout, applying filters if specified. +/// +/// # Arguments +/// +/// * `cmd` - Clap command for error handling. +/// * `settings` - Global settings, including force output flag. +/// * `ids` - List of item IDs (at most one). +/// * `tags` - List of tags to match (mutually exclusive with IDs). +/// * `conn` - Database connection. +/// * `data_path` - Path to data directory. +/// * `filter_chain` - Optional pre-parsed filter chain to apply to content. +/// +/// # Returns +/// +/// `Result<()>` on success, or an error if item not found or output fails. pub fn mode_get( cmd: &mut Command, settings: &config::Settings, diff --git a/src/modes/mod.rs b/src/modes/mod.rs index 7648c89..58458f4 100644 --- a/src/modes/mod.rs +++ b/src/modes/mod.rs @@ -1,6 +1,9 @@ #[cfg(feature = "server")] pub mod server; + +/// Common utilities for all modes, including column types and output formatting. pub mod common; + pub mod delete; pub mod diff; pub mod generate_config; @@ -11,15 +14,36 @@ pub mod save; pub mod status; pub mod status_plugins; +/// Column types, output formats, and formatting utilities shared across modes. pub use common::{ColumnType, OutputFormat, format_size, settings_output_format}; + +/// Deletes items from the database by ID. pub use delete::mode_delete; + +/// Compares two items and shows differences. pub use diff::mode_diff; + +/// Generates a default configuration file. pub use generate_config::mode_generate_config; + +/// Retrieves and outputs item content. pub use get::mode_get; + +/// Displays detailed information about items. pub use info::mode_info; + +/// Lists items with optional filtering. pub use list::mode_list; + +/// Saves new item content with optional tags and metadata. pub use save::mode_save; + #[cfg(feature = "server")] +/// Starts the HTTP server for REST API access. pub use server::mode_server; + +/// Shows status of directories and compression support. pub use status::mode_status; + +/// Lists available plugins and their configurations. pub use status_plugins::mode_status_plugins; diff --git a/src/parser/mod.rs b/src/parser/mod.rs index 60b58aa..5374f00 100644 --- a/src/parser/mod.rs +++ b/src/parser/mod.rs @@ -1,3 +1,4 @@ +/// Parsing utilities for filters and other inputs. pub mod filter_parser; pub use filter_parser::{FilterParser, parse_filter_string}; diff --git a/src/services/error.rs b/src/services/error.rs index bb4bf16..5d49c24 100644 --- a/src/services/error.rs +++ b/src/services/error.rs @@ -1,5 +1,6 @@ use thiserror::Error; +/// Core error types used across services for consistent error handling. #[derive(Error, Debug)] pub enum CoreError { #[error("Database error: {0}")]