docs: Add Rustdoc for modules, functions, and structs

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

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<NumberOrString>,
 }
 
-/**
- * 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<u16>,
 }
 
-/**
- * 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> {

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)

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,

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,

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,

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;

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};

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}")]