Initialisation depot

2025-11-30 09:58:00 +01:00
commit 56d8cd96c8
28 changed files with 3154 additions and 0 deletions
--- a/doc/README.md
+++ b/doc/README.md
@@ -0,0 +1,143 @@
+# 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