[Refactor] Add comprehensive module-level documentation

[oleander]

Context

Most modules lack top-level documentation explaining their purpose and usage. This makes the codebase harder to understand and navigate.

Priority

🟢 LOW - Important for maintainability but not blocking

Required Documentation Format

Each module must have:

//! Brief one-sentence description.
//!
//! # Overview  
//! Detailed explanation of what this module does and why it exists.
//!
//! # Examples
//! ```rust
//! # Example usage
//! ```
//!
//! # Architecture
//! How this fits into the larger system (if applicable).

Modules to Document

Priority 1: Core modules (must document)

1. src/diff/mod.rs

//! Git diff parsing and processing.
//!
//! # Overview
//! This module handles parsing git diffs into structured data and
//! processing them with token management for LLM consumption.
//!
//! # Submodules
//! - `parser`: Parses raw git diff text into structured files
//! - `processor`: Converts diffs to patches with token limits
//! - `optimization`: Parallel processing for large diffs
//! - `traits`: Utility traits for diff operations
//!
//! # Examples
//! ```rust,no_run
//! use git_ai::diff::parser::parse_diff;
//! 
//! let diff = "diff --git a/file.txt b/file.txt...";
//! let files = parse_diff(diff)?;
//! ```

2. src/generation/mod.rs - Document multi-step algorithm

3. src/api/mod.rs - Document API integrations

4. src/config.rs - Document configuration system

5. src/model.rs - Document token management strategy

Priority 2: Important modules

6. src/hook.rs - Explain diff processing architecture
7. src/filesystem.rs - Document file operations
8. src/function_calling.rs - Explain OpenAI function calling
9. src/profiling.rs - Document performance tracking

Priority 3: Support modules

10. src/style.rs
11. src/debug_output.rs
12. src/client.rs
13. src/commit.rs

Steps

For each module:

1. Add module-level doc comment at the top
2. Include example if public API
3. Explain architecture if complex
4. Document submodules if applicable
5. Add links to related modules

Template to Use

//! [Brief description - one sentence]
//!
//! # Overview
//! 
//! [2-3 paragraphs explaining:
//!  - What this module does
//!  - Why it exists
//!  - Key concepts or algorithms]
//!
//! # Examples
//!
//! ```rust,no_run
//! use git_ai::module::function;
//! 
//! let result = function()?;
//! assert!(!result.is_empty());
//! ```
//!
//! # Architecture
//!
//! [Diagram or explanation of how this fits in the system]
//! 
//! ## Submodules (if applicable)
//!
//! - [`submodule1`]: Description
//! - [`submodule2`]: Description
//!
//! # See Also
//!
//! - [`related_module`]: Related functionality

Verification Criteria

✅ Pass:

• All Priority 1 modules have comprehensive documentation
• All Priority 2 modules have at least brief documentation
• All Priority 3 modules have at least one-line description
• Examples compile (use no_run if they need setup)
• cargo doc builds without warnings
• cargo doc --open - documentation looks good in browser
• Cross-references between modules work (clickable links)

How to Build and Review Docs

# Build documentation
cargo doc --no-deps

# Open in browser
cargo doc --no-deps --open

# Check for warnings
cargo doc 2>&1 | grep -i warning

# Should output: (no warnings)

Estimated Time

4-5 hours

Dependencies

• Issue Use structopt instead of clap #8 (Consolidate multi-step) - final module structure needed

Labels

• documentation
• refactor
• developer-experience