[Refactor] Add documentation to all public functions

[oleander]

Context

Many public functions lack documentation, making the API harder to understand and use. This issue adds comprehensive documentation to all public functions.

Priority

🟢 LOW - Important for maintainability

Documentation Standard

Every public function must have:

/// Brief one-line description.
///
/// More detailed explanation of what the function does, its algorithm,
/// and any important considerations.
///
/// # Arguments
/// * `param1` - Description of parameter
/// * `param2` - Description of parameter
///
/// # Returns
/// * `Result<Type>` - Description of return value
///
/// # Errors
/// Returns error if:
/// - Condition 1
/// - Condition 2
///
/// # Examples
/// ```rust,no_run
/// let result = function(arg1, arg2)?;
/// assert!(result.is_valid());
/// ```
///
/// # Panics
/// Panics if... (only include if function can panic)
pub fn function(param1: Type1, param2: Type2) -> Result<Type> {
    // ...
}

Priority Functions to Document

High Priority (Public API)

1. In src/commit.rs:

   • generate() - Main entry point
   • create_commit_request()
   • get_instruction_template()
   • token_used()

2. In src/generation/multi_step.rs:

   • generate_with_api()
   • generate_local()

3. In src/generation/fallback.rs:

   • generate_with_fallback()
   • All trait methods in GenerationStrategy

4. In src/diff/parser.rs:

   • parse_diff()

5. In src/diff/processor.rs:

   • All trait methods in PatchDiff and PatchRepository

6. In src/api/auth.rs:

   • get_api_key()
   • validate_api_key()

7. In src/config.rs:

   • AppConfig::new()
   • AppConfig::save()
   • All update methods

8. In src/model.rs:

   • Model::count_tokens()
   • Model::truncate()
   • Model::context_size()

Medium Priority (Less frequently used)

9. In src/filesystem.rs:

   • All public methods in File and Dir

10. In src/function_calling.rs:

    • create_commit_function_tool()
    • parse_commit_function_response()

11. In src/openai.rs:

    • generate_commit_message()
    • create_openai_config()

Steps

1. For each function:

   • Read the implementation to understand what it does
   • Write clear description
   • Document all parameters
   • Document return value
   • List all possible errors
   • Add example if public API
   • Note panics if applicable

2. Use consistent language:

   • Present tense: "Generates", not "Will generate"
   • Active voice: "Parses the diff", not "The diff is parsed"
   • Be specific about errors and edge cases

3. Add examples that:

   • Are realistic and useful
   • Compile (use no_run if needed)
   • Show typical usage
   • Cover error handling

4. Cross-reference related functions:

   /// See also [`related_function`] for...
   

Example: Before and After

Before:

pub fn parse_diff(diff: &str) -> Result<Vec<ParsedFile>> {
    // Implementation
}

After:

/// Parses a git diff into individual file changes.
///
/// Handles various diff formats including standard git diff output,
/// diffs with commit hashes, and various path prefixes (a/, b/, c/, i/).
/// Also correctly handles deleted files (/dev/null paths).
///
/// # Arguments
/// * `diff` - Raw git diff text to parse
///
/// # Returns
/// * `Result<Vec<ParsedFile>>` - Parsed file changes, one per modified file
///
/// # Errors
/// Returns error if:
/// - Diff format is completely unrecognizable
/// - File paths cannot be extracted
///
/// # Examples
/// ```rust,no_run
/// use git_ai::diff::parser::parse_diff;
/// 
/// let diff = r#"
/// diff --git a/src/main.rs b/src/main.rs
/// index 1234567..abcdefg 100644
/// --- a/src/main.rs
/// +++ b/src/main.rs
/// @@ -1,3 +1,4 @@
/// +// New comment
///  fn main() {
///      println!("Hello");
///  }
/// "#;
/// 
/// let files = parse_diff(diff)?;
/// assert_eq!(files.len(), 1);
/// assert_eq!(files[0].path, "src/main.rs");
/// assert_eq!(files[0].operation, "modified");
/// # Ok::<(), anyhow::Error>(())
/// ```
pub fn parse_diff(diff: &str) -> Result<Vec<ParsedFile>> {
    // Implementation
}

Verification Criteria

✅ Pass:

• All high-priority functions documented
• All medium-priority functions have at least brief docs
• Examples compile successfully
• cargo doc builds without warnings
• cargo doc --open shows complete documentation
• No "missing documentation" warnings with #![warn(missing_docs)]

Check Your Work

# Build docs and check for issues
cargo doc --no-deps 2>&1 | tee doc-output.txt

# Look for "missing documentation" warnings
cat doc-output.txt | grep -i "missing"

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

# Optionally: Enable missing_docs lint temporarily
# Add to lib.rs: #![warn(missing_docs)]
# Then: cargo check

Estimated Time

6-8 hours (spread across multiple sessions)

Dependencies

• Issue Remove unused Dockerfile and related release script #10 (Module documentation) - provides context for function docs

Notes

• Can be done incrementally (one module at a time)
• Commit after completing each module
• Focus on quality over speed

Labels

• documentation
• refactor
• api
• developer-experience