Skip to content

API Documentation (Doxygen)

Purpose

Configuration and guidelines for generating API reference documentation from C++ source code using Doxygen. This directory contains the infrastructure for automatic API documentation, not the documentation content itself.

Contents

Configuration Files

  • Doxyfile - Main Doxygen configuration
  • Configured to scan 04_CORE/ and 05_MODULES/
  • Outputs to var/docs/api/
  • Includes custom theme and branding

Theme Customization

  • doxygen_theme/custom.css - AudioLab visual theme
  • doxygen_theme/header.html - Custom header with branding
  • doxygen_theme/footer.html - Custom footer with links

Guidelines

  • doc_comments_guide.md - How to write documentation comments
  • api_doc_standards.md - Mandatory documentation requirements

Quick Start

Prerequisites

# Install Doxygen
winget install doxygen

# Verify installation
doxygen --version  # Should be 1.9.8 or later

Generate API Documentation

# From this directory
cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_00_api_documentation"

# Run Doxygen
doxygen Doxyfile

# Open generated docs
start ../../../../var/docs/api/html/index.html

Using the Master Script

# From automation directory
cd ../03_11_05_documentation_automation
.\generate_docs.ps1 -Target api

Configuration Overview

Key Settings in Doxyfile

Setting Value Purpose
INPUT ../../04_CORE, ../../05_MODULES Source code to document
OUTPUT_DIRECTORY ../../../../var/docs/api Where docs are generated
RECURSIVE YES Scan subdirectories
EXTRACT_ALL NO Only document explicitly documented code
GENERATE_HTML YES Generate HTML output
SOURCE_BROWSER YES Include source code browser
GENERATE_TREEVIEW YES Sidebar navigation
WARN_IF_UNDOCUMENTED YES Warn about missing docs

Custom Theme Features

  • AudioLab Branding - Custom header/footer with project logo
  • Modern Design - Clean, professional appearance
  • Syntax Highlighting - Color-coded code examples
  • Responsive Layout - Works on mobile/tablet
  • Search - Full-text search capability

Documentation Standards

What Must Be Documented (100% Compliance)

  1. All public classes and structs
  2. All public functions and methods
  3. All function parameters (with @param)
  4. All return values (with @return)
  5. All exceptions (with @throws)
  • Code examples (@code / @endcode)
  • Preconditions (@pre)
  • Postconditions (@post)
  • Thread-safety notes (@note)
  • Real-time safety status
  • Performance characteristics

Example Documentation

/**
 * @brief Apply gain with smooth ramping to prevent clicks
 *
 * Linearly interpolates from current gain to target gain over
 * the buffer length. Safe for real-time use.
 *
 * @param buffer Audio buffer to process (must not be null)
 * @param size Number of samples (must be > 0)
 * @param targetGain Target gain (0.0 = silence, 1.0 = unity)
 *
 * @pre buffer != nullptr
 * @pre size > 0
 * @post Buffer samples scaled by interpolated gain
 *
 * @note RT-SAFE: No allocations, no locks, O(n) complexity
 * @note Thread-safe for concurrent processing of different buffers
 */
void applyGainWithRamp(float* buffer, size_t size, float targetGain) noexcept;

Validation

Check Documentation Coverage

# Generate docs and check for warnings
doxygen Doxyfile 2>&1 | Select-String "warning.*not documented"

Expected Output Structure

var/docs/api/
├── html/
│   ├── index.html           # Main entry point
│   ├── annotated.html       # Class list
│   ├── files.html           # File list
│   ├── namespaces.html      # Namespace list
│   ├── functions.html       # Function index
│   └── search/              # Search index
└── xml/                     # XML output (for other tools)

Integration

CI/CD Pipeline

# .github/workflows/docs.yml
- name: Generate API Documentation
  run: |
    cd "2 - FOUNDATION/03_INFRA/03_11_documentation_platform/03_11_00_api_documentation"
    doxygen Doxyfile
    if ($LASTEXITCODE -ne 0) { exit 1 }

Pre-Commit Hook

# .git/hooks/pre-commit
# Check for undocumented public APIs
doxygen Doxyfile 2>&1 | Select-String "warning" > $null
if ($LASTEXITCODE -eq 0) {
    Write-Error "Undocumented public APIs detected"
    exit 1
}

Customization

Add Custom Aliases

Edit Doxyfile: 

ALIASES = realtime="@note RT-SAFE: Real-time safe" \
          unsafe="@warning RT-UNSAFE: Not real-time safe"

Usage: 

/** @brief Process audio
 *  @realtime
 */
void process(float* buffer, size_t size);

Change Theme Colors

Edit doxygen_theme/custom.css: 

:root {
  --primary-color: #YOUR_COLOR;
  --secondary-color: #YOUR_COLOR;
}

  1. Place logo in doxygen_theme/logo.png
  2. Edit Doxyfile: PROJECT_LOGO = doxygen_theme/logo.png

Troubleshooting

Doxygen Not Found

# Install via winget
winget install doxygen

# Or download from: https://www.doxygen.nl/download.html

No Output Generated

  • Check Doxyfile paths are correct (relative to Doxyfile location)
  • Ensure source files contain documentation comments
  • Verify OUTPUT_DIRECTORY is writable

Warnings About Undocumented Code

  • Review api_doc_standards.md for requirements
  • Add missing @brief, @param, @return tags
  • Use EXTRACT_ALL = YES temporarily to see all items

Custom Theme Not Applied

  • Verify paths in Doxyfile:
  • HTML_HEADER = doxygen_theme/header.html
  • HTML_FOOTER = doxygen_theme/footer.html
  • HTML_EXTRA_STYLESHEET = doxygen_theme/custom.css

References

Documentation

Examples

Maintenance

Regular Tasks

  • Update PROJECT_NUMBER in Doxyfile for releases
  • Review and improve theme styling
  • Add new documentation aliases as needed
  • Update standards guide based on team feedback

Quality Metrics

Track these metrics in CI/CD: - Coverage: % of public APIs documented - Warnings: Number of documentation warnings - Examples: % of classes with code examples - Completeness: % with all required tags (@brief, @param, @return)

Support

  • Questions: See doc_comments_guide.md
  • Standards: See api_doc_standards.md
  • Issues: Open ticket in project tracker