DCC-Bench/doc/README.md

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:

sudo apt-get install doxygen graphviz

macOS:

brew install doxygen graphviz

Fedora/RHEL:

sudo dnf install doxygen graphviz

Windows: Download from doxygen.nl

Generate Documentation

Run the generation script from the project root:

./generate_docs.sh

Or manually:

doxygen Doxyfile

View Documentation

Open the generated HTML documentation:

# 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:

/**
 * @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:

# 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