# API Documentation

This directory contains the auto-generated API documentation for the Locomotive Test Bench project.

## Generating Documentation

### Prerequisites

Install Doxygen (and optionally Graphviz for diagrams):

**Ubuntu/Debian:**
```bash
sudo apt-get install doxygen graphviz
```

**macOS:**
```bash
brew install doxygen graphviz
```

**Fedora/RHEL:**
```bash
sudo dnf install doxygen graphviz
```

**Windows:**
Download from [doxygen.nl](https://www.doxygen.nl/download.html)

### Generate Documentation

Run the generation script from the project root:

```bash
./generate_docs.sh
```

Or manually:

```bash
doxygen Doxyfile
```

### View Documentation

Open the generated HTML documentation:

```bash
# Linux
xdg-open doc/html/index.html

# macOS
open doc/html/index.html

# Windows
start doc/html/index.html
```

Or navigate to: `doc/html/index.html` in your browser.

## Documentation Structure

The generated documentation includes:

### Main Pages
- **Main Page**: Project overview and introduction
- **Classes**: All class definitions with member details
- **Files**: Source and header file listings
- **Namespaces**: Code organization structure

### For Each Class
- **Detailed Description**: Purpose and functionality
- **Member Functions**: All public/private methods
- **Member Variables**: All data members
- **Constructor/Destructor**: Object lifecycle
- **Usage Examples**: Where available

### Key Classes Documented

1. **Config** - Configuration management and persistent storage
2. **WiFiManager** - WiFi connectivity (AP and Client modes)
3. **MotorController** - DC motor control via LM18200
4. **DCCGenerator** - DCC protocol signal generation
5. **LEDIndicator** - WS2812 LED status indicators
6. **WebServerManager** - Web interface and REST API

## Customizing Documentation

Edit `Doxyfile` in the project root to customize:

- `PROJECT_NAME` - Project title
- `PROJECT_NUMBER` - Version number
- `PROJECT_BRIEF` - Short description
- `OUTPUT_DIRECTORY` - Where to generate docs
- `EXTRACT_PRIVATE` - Include private members
- `GENERATE_LATEX` - Generate PDF documentation
- `HAVE_DOT` - Enable class diagrams (requires Graphviz)

## Documentation Format

The code uses **Doxygen-style comments**:

```cpp
/**
 * @brief Short description
 * 
 * Detailed description can span
 * multiple lines.
 * 
 * @param paramName Description of parameter
 * @return Description of return value
 * @note Additional notes
 * @warning Important warnings
 */
void exampleFunction(int paramName);
```

## Updating Documentation

When you modify code:

1. Update Doxygen comments in source files
2. Run `./generate_docs.sh` to regenerate
3. Review changes in browser
4. Commit updated source files (not generated HTML)

## CI/CD Integration

To auto-generate docs in CI/CD:

```yaml
# Example GitHub Actions
- name: Generate Documentation
  run: |
    sudo apt-get install doxygen
    ./generate_docs.sh
```

## Notes

- The `doc/` directory is typically added to `.gitignore`
- Only source comments are version controlled
- Documentation is regenerated as needed
- HTML output is ~2-5 MB depending on project size