Improved documentation across the tool

Signed-off-by: Adam Poulemanos <[email protected]>

Author: bashandbone

.roomodes

@@ -0,0 +1,16 @@
+{
+  "customModes": [
+    {
+      "slug": "plain-docs-writer",
+      "name": "📝 Plain Documentation Writer",
+      "roleDefinition": "You are a technical documentation expert. You specialize in creating clear and developer-friendly documentation for software projects. Your role includes: (1) Writing clear, concise technical documentation. (2) Creating and maintaining README files, API documentation, and user guides. (3) Following documentation best practices and style guides. (4) Using your deep understanding of software development to explain complex concepts simply. (5) Organizing documentation in a logical, easily navigable structure.",
+      "whenToUse": "Use this mode for writing or editing documentation.",
+      "customInstructions": "Focus on creating documentation that is clear, concise, and follows a consistent style. Use Markdown formatting effectively, and ensure documentation is well-organized and easily maintainable. Don't over-document. If a function or feature is well-typed and self-explanatory, a sentence may suffice. Use plain language, avoid jargon and idioms, and ensure that the documentation is accessible to developers of all skill levels. Always use active voice and present tense -- instead of \"The function adds two numbers,\" write \"Adds two numbers.\"\n\n If you see 'to-do' like comments that aren't marked as TODO, rewrite them as `TODO:`s that are actionable and clear.",
+      "groups": [
+        "read",
+        "edit",
+        "browser"
+      ]
+    }
+  ]
+}

custom_modes.json

@@ -1,49 +1,93 @@
+#![doc = r#"
+Command-line argument definitions for the `submod` tool.
+
+Defines the CLI structure and subcommands using [`clap`] for managing git submodules with sparse checkout support.
+
+# Overview
+
+- Parses CLI arguments for the `submod` binary.
+- Supports commands for adding, checking, initializing, updating, resetting, and syncing submodules.
+- Allows specifying a custom configuration file (default: `submod.toml`).
+
+# Commands
+
+- [`Commands::Add`](src/commands.rs): Adds a new submodule configuration.
+- [`Commands::Check`](src/commands.rs): Checks submodule status and configuration.
+- [`Commands::Init`](src/commands.rs): Initializes missing submodules.
+- [`Commands::Update`](src/commands.rs): Updates all submodules.
+- [`Commands::Reset`](src/commands.rs): Hard resets submodules (stash, reset --hard, clean).
+- [`Commands::Sync`](src/commands.rs): Runs a full sync (check, init, update).
+
+# Usage Example
+
+```sh
+submod add my-lib libs/my-lib https://github.com/example/my-lib.git --sparse-paths "src/,include/" --settings "ignore=all"
+submod check
+submod init
+submod update
+submod reset --all
+submod sync
+```
+
+# Configuration
+
+Use the `--config` option to specify a custom config file.
+
+See the [README.md](../README.md) for full usage and configuration details.
+"#]
+
 use clap::{Parser, Subcommand};
 use std::path::PathBuf;
 
+/// Top-level CLI parser for the `submod` tool.
+///
+/// Accepts a subcommand and an optional config file path.
 #[derive(Parser)]
 #[command(name = "submod")]
 #[command(about = "Manage git submodules with sparse checkout support")]
 pub struct Cli {
+    /// Subcommand to execute.
     #[command(subcommand)]
     pub command: Commands,
 
+    /// Path to the configuration file (default: submod.toml).
     #[arg(short, long, default_value = "submod.toml")]
     pub config: PathBuf,
 }
 
+/// Supported subcommands for the `submod` tool.
 #[derive(Subcommand)]
 pub enum Commands {
-    /// Add a new submodule configuration
+    /// Adds a new submodule configuration.
     Add {
-        /// Submodule name
+        /// Submodule name.
         name: String,
-        /// Local path for the submodule
+        /// Local path for the submodule.
         path: String,
-        /// Git repository URL
+        /// Git repository URL.
         url: String,
-        /// Sparse checkout paths (comma-separated)
+        /// Sparse checkout paths (comma-separated).
         #[arg(short, long)]
         sparse_paths: Option<String>,
-        /// Git settings like "ignore=all"
+        /// Additional git settings (e.g., "ignore=all").
         #[arg(short = 'S', long)]
         settings: Option<String>,
     },
-    /// Check submodule status and configuration
+    /// Checks submodule status and configuration.
     Check,
-    /// Initialize missing submodules
+    /// Initializes missing submodules.
     Init,
-    /// Update all submodules
+    /// Updates all submodules.
     Update,
-    /// Hard reset submodules (stash, reset --hard, clean)
+    /// Hard resets submodules (stash, reset --hard, clean).
     Reset {
-        /// Reset all submodules
+        /// Reset all submodules.
         #[arg(short, long)]
         all: bool,
-        /// Specific submodule names to reset
+        /// Specific submodule names to reset.
         #[arg(required_unless_present = "all")]
         names: Vec<String>,
     },
-    /// Run full sync: check, init, update
+    /// Runs a full sync: check, init, update.
     Sync,
 }

src/commands.rs

@@ -1,3 +1,25 @@
+#![doc = r#"
+Configuration types and utilities for submod.
+
+Defines serializable wrappers for git submodule options, project-level defaults, and submodule
+configuration management. Supports loading and saving configuration in TOML format.
+
+Main Types:
+- SerializableIgnore, SerializableFetchRecurse, SerializableBranch, SerializableUpdate: Wrappers for git submodule config enums, supporting (de)serialization.
+- SubmoduleGitOptions: Git-specific options for a submodule.
+- SubmoduleDefaults: Project-level default submodule options.
+- SubmoduleConfig: Configuration for a single submodule.
+- Config: Main configuration structure, containing defaults and all submodules.
+
+Features:
+- Load and save configuration from/to TOML files.
+- Serialize/deserialize submodule options for config files.
+- Manage submodule entries and defaults programmatically.
+
+TODO:
+- Add validation for config values when loading from file.
+"#]
+
 use anyhow::{Context, Result};
 use bstr::BStr;
 use gix_submodule::config::{Branch, FetchRecurse, Ignore, Update};
@@ -6,9 +28,7 @@ use std::fs;
 use std::{collections::HashMap, path::Path};
 use toml_edit::{Array, DocumentMut, Item, Table, value};
 
-/**========================================================================
- **                  Wrappers for Gix Submodule Config
- *========================================================================**/
+
 /// Serializable wrapper for [`Ignore`] config
 #[derive(Debug, Default, Clone, Copy, Ord, PartialOrd, Eq, PartialEq, Hash)]
 pub struct SerializableIgnore(pub Ignore);
@@ -221,7 +241,6 @@ impl From<SerializableUpdate> for Update {
 }
 
 /// Git options for a submodule
-/// Git-specific options for submodule configuration
 #[derive(Debug, Default, Clone, Ord, PartialOrd, Eq, PartialEq, Hash, Serialize, Deserialize)]
 pub struct SubmoduleGitOptions {
     /// How to handle dirty files when updating submodules

src/config.rs

@@ -1,7 +1,48 @@
-//! Gitoxide-maximized submodule manager
-//!
-//! This module implements the submodule manager with maximum use of gitoxide/gix APIs
-//! and strategic fallbacks only where necessary.
+#![doc = r#"
+# Gitoxide-Based Submodule Manager
+
+Provides core logic for managing git submodules using the [`gitoxide`](https://github.com/Byron/gitoxide) library, with fallbacks to `git2` and the Git CLI when needed. Supports advanced features like sparse checkout and TOML-based configuration.
+
+## Overview
+
+- Loads submodule configuration from a TOML file.
+- Adds, initializes, updates, resets, and checks submodules.
+- Uses `gitoxide` APIs where possible for performance and reliability.
+- Falls back to `git2` (if enabled) or the Git CLI for unsupported operations.
+- Supports sparse checkout configuration per submodule.
+
+## Key Types
+
+- [`SubmoduleError`](src/gitoxide_manager.rs:14): Error type for submodule operations.
+- [`SubmoduleStatus`](src/gitoxide_manager.rs:55): Reports the status of a submodule, including cleanliness, commit, remotes, and sparse checkout state.
+- [`SparseStatus`](src/gitoxide_manager.rs:77): Describes the sparse checkout configuration state.
+- [`GitoxideSubmoduleManager`](src/gitoxide_manager.rs:94): Main struct for submodule management.
+
+## Main Operations
+
+- [`GitoxideSubmoduleManager::add_submodule()`](src/gitoxide_manager.rs:207): Adds a new submodule, configuring sparse checkout if specified.
+- [`GitoxideSubmoduleManager::init_submodule()`](src/gitoxide_manager.rs:643): Initializes a submodule, adding it if missing.
+- [`GitoxideSubmoduleManager::update_submodule()`](src/gitoxide_manager.rs:544): Updates a submodule using the Git CLI.
+- [`GitoxideSubmoduleManager::reset_submodule()`](src/gitoxide_manager.rs:574): Resets a submodule (stash, hard reset, clean).
+- [`GitoxideSubmoduleManager::check_all_submodules()`](src/gitoxide_manager.rs:732): Checks the status of all configured submodules.
+
+## Sparse Checkout Support
+
+- Checks and configures sparse checkout for each submodule based on the TOML config.
+- Writes sparse-checkout patterns and applies them using the Git CLI.
+
+## Error Handling
+
+All operations return [`SubmoduleError`](src/gitoxide_manager.rs:14) for consistent error reporting.
+
+## TODOs
+
+- TODO: Implement submodule addition using gitoxide APIs when available ([`add_submodule_with_gix`](src/gitoxide_manager.rs:278)).
+
+## Usage
+
+Use this module as the backend for CLI commands to manage submodules in a repository. See the project [README](README.md) for usage examples and configuration details.
+"#]
 
 use crate::config::{Config, SubmoduleConfig, SubmoduleGitOptions};
 use gix::Repository;
@@ -38,11 +79,11 @@ pub enum SubmoduleError {
 
     /// Submodule not found in repository
     #[error("Submodule {name} not found")]
-    SubmoduleNotFound { name: String },
+    SubmoduleNotFound {
+        /// Name of the missing submodule.
+        name: String,
+    },
 
-    /// Sparse checkout configuration error
-    #[error("Invalid sparse checkout configuration: {reason}")]
-    SparseCheckoutError { reason: String },
 
     /// Repository access or validation error
     #[error("Repository not found or invalid")]
@@ -101,6 +142,16 @@ pub struct GitoxideSubmoduleManager {
 }
 
 impl GitoxideSubmoduleManager {
+    /// Creates a new `GitoxideSubmoduleManager` by loading configuration from the given path.
+    ///
+    /// # Arguments
+    ///
+    /// * `config_path` - Path to the TOML configuration file.
+    ///
+    /// # Errors
+    ///
+    /// Returns `SubmoduleError::RepositoryError` if the repository cannot be discovered,
+    /// or `SubmoduleError::ConfigError` if the configuration fails to load.
     pub fn new(config_path: PathBuf) -> Result<Self, SubmoduleError> {
         // Use gix::discover for repository detection
         let repo = gix::discover(".").map_err(|_| SubmoduleError::RepositoryError)?;

src/gitoxide_manager.rs

@@ -1,7 +1,19 @@
-//! Submod - Git submodule manager with sparse checkout support using gitoxide
+//! Library entry point for submod, a Git submodule manager with sparse checkout support.
 //!
-//! This library exists only for testing purposes. We're a CLI tool, not a library.
-//! You're welcome to use it as a library, but we don't guarantee any API stability.
+//! This crate is primarily intended for CLI use. The library API is not stable and may change.
+//!
+//! # Modules
+//! - [`config`]: Submodule configuration management.
+//! - [`gitoxide_manager`]: Implementation of submodule operations using gitoxide.
+//!
+//! # Exports
+//! - Common types and managers for use in tests or advanced integrations.
+//!
+//! # Version
+//! - Exposes the current crate version as [`VERSION`].
+//!
+//! # Note
+//! The API is not guaranteed to be stable. Use at your own risk.
 
 /// Configuration management for submodules
 pub mod config;

src/lib.rs

@@ -1,7 +1,21 @@
-//! Submod - Git submodule manager with sparse checkout support
-//!
-//! A CLI tool for managing Git submodules with advanced features like sparse checkout
-//! support using the gitoxide library for high performance operations.
+#![doc = r#"
+Main entry point for the submod CLI tool.
+
+Parses command-line arguments and dispatches submodule management commands using the
+[`GitoxideSubmoduleManager`]. Supports adding, checking, initializing, updating, resetting,
+and syncing submodules with advanced features like sparse checkout.
+
+# Commands
+
+- `add`: Add a new submodule with optional sparse paths.
+- `check`: Check the status of all configured submodules.
+- `init`: Initialize all submodules from config.
+- `update`: Update all submodules.
+- `reset`: Reset specified or all submodules.
+- `sync`: Run check, init, and update in sequence.
+
+Exits with an error if any operation fails.
+"#]
 
 mod commands;
 mod config;
@@ -12,8 +26,6 @@ use crate::gitoxide_manager::GitoxideSubmoduleManager;
 use anyhow::Result;
 use clap::Parser;
 
-// Old SubmoduleManager removed - now using GitoxideSubmoduleManager
-
 fn main() -> Result<()> {
     let cli = Cli::parse();