144 lines
3.1 KiB
Markdown
144 lines
3.1 KiB
Markdown
# 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
|