# 📖 Docs Guide

The `docs` command uses AI to generate language-appropriate documentation comments for your source files. It supports a wide range of programming languages and documentation styles.

### Usage

Generate language-appropriate documentation comments using Grok AI.

```bash
# Preview and confirm
grokkit docs main.go

# Auto-apply without confirmation
grokkit docs handlers.go models.go --auto-apply

# Document multiple files at once
grokkit docs cmd/*.go --auto-apply

# Use specific model
grokkit docs app.py -m grok-4
```

### Supported doc styles by language

| Language | Style |
|----------|-------|
| Go | godoc (`// FuncName does...`) |
| Python | PEP 257 docstrings (`"""Summary\n\nArgs:..."""`) |
| C / C++ | Doxygen (`/** @brief ... @param ... @return ... */`) |
| JavaScript / TypeScript | JSDoc (`/** @param {type} name ... */`) |
| Rust | rustdoc (`/// Summary\n/// # Arguments`) |
| Ruby | YARD (`# @param [Type] name`) |
| Java | Javadoc (`/** @param ... @return ... */`) |
| Shell | Shell comments (`# function: desc, # Args: ...`) |

### Safety features

- Shows first 50 lines of documented code as preview
- Requires confirmation (unless `--auto-apply`)

### Options

| Flag | Description |
|------|-------------|
| `--auto-apply` | Apply documentation without confirmation |
| `--model`, `-m` | Override the default model (e.g., `grok-4`) |

### How it Works

1. **Language Detection**: Grokkit detects the language of each file to select the appropriate documentation style.
2. **Contextual Analysis**: It reads the file and prepares a prompt for Grok.
3. **AI Generation**: Grok generates the documentation comments for all public functions, methods, and types.
4. **Interactive Preview**: Grokkit shows you a preview of the documented code.
5. **Confirmation**: You review and confirm before the changes are applied to your file (unless you use `--auto-apply`).

### Best Practices

- **Document public APIs**: Use `docs` to ensure your project's public interface is well-documented.
- **Review for Accuracy**: Always read the generated documentation to ensure it accurately reflects the function's purpose and behavior.
- **Use for complex code**: For particularly complex functions, AI-generated documentation can be very helpful for clarifying logic.