This guide explains how to generate and use the ReUseX API documentation.

Overview

ReUseX uses Doxygen to automatically generate comprehensive API documentation from the C++ source code. The documentation includes:

API Reference: Complete documentation for all classes, functions, and namespaces
Class Diagrams: Inheritance hierarchies and collaboration diagrams
Source Browser: Browse and search through the source code
Module Organization: Documentation organized by functional modules
Cross-references: Links between related functions, classes, and files

Prerequisites

Required

Doxygen (version 1.8.0 or higher)

Optional

Graphviz (dot tool): Required for generating class diagrams and dependency graphs

Installation

Ubuntu/Debian:

sudo apt-get install doxygen graphviz

Fedora/RHEL:

sudo dnf install doxygen graphviz

macOS (Homebrew):

brew install doxygen graphviz

NixOS/Nix:

nix-shell -p doxygen graphviz
# Or enter the development shell:
nix develop

Generating Documentation

Method 1: Using CMake (Recommended)

From your build directory:

# Configure with documentation enabled (ON by default)
cmake -B build -DBUILD_DOCUMENTATION=ON
 
# Generate the documentation
cmake --build build --target doc

Method 2: Using Doxygen Directly

From the project root:

doxygen Doxyfile

Output Location

Generated documentation is placed in the doc/ directory:

HTML: doc/html/index.html - Main entry point for the HTML documentation
Search: Full-text search available in the HTML output

Viewing Documentation

Open the documentation in your web browser:

# Linux
xdg-open doc/html/index.html
 
# macOS
open doc/html/index.html
 
# Windows
start doc/html/index.html

Documentation Structure

The generated documentation is organized into several sections:

Main Page: Overview from README.md
Namespaces: Organized by namespace hierarchy
Classes: Complete class reference with inheritance diagrams
Files: Documentation organized by source files
Examples: Code examples (when available)

Key Namespaces

ReUseX: Core library functionality
- ReUseX::io: Input/output operations
- ReUseX::core: Core data structures and algorithms
rux: Command-line interface utilities
pcl: PCL extensions (custom implementations)
spdmon: Monitoring utilities

CMake Options

Control documentation generation with CMake options:

# Disable documentation generation
cmake -B build -DBUILD_DOCUMENTATION=OFF
 
# Enable documentation (default)
cmake -B build -DBUILD_DOCUMENTATION=ON

Customizing Documentation

Doxyfile Configuration

The Doxyfile in the project root contains all Doxygen settings. Key configurations:

PROJECT_NAME: ReUseX
INPUT: Source directories (include/ReUseX, include/rux, etc.)
OUTPUT_DIRECTORY: doc/
GENERATE_HTML: YES (HTML output enabled)
GENERATE_LATEX: NO (LaTeX output disabled by default)
RECURSIVE: YES (recurse into subdirectories)
EXTRACT_ALL: YES (document all entities)
SOURCE_BROWSER: YES (include source code browsing)
HAVE_DOT: YES (use Graphviz for diagrams)

Modifying Settings

Edit Doxyfile to customize:

Output formats (HTML, LaTeX, XML)
Extraction settings (private members, static functions)
Diagram generation options
Search engine configuration

Writing Documentation

Documentation Comments

Doxygen parses special comment blocks in the source code:

int myFunction(int param1, int param2);

Troubleshooting

Common Issues

Issue: "Doxygen not found"

Solution: Install Doxygen using your package manager

Issue: "dot not found" or missing diagrams

Solution: Install Graphviz for diagram generation

Issue: Documentation is empty or incomplete

Solution: Check that source files have proper documentation comments

Issue: Build fails with Doxygen warnings

Solution: Review warnings and fix documentation syntax in source files

Disabling Documentation

If you don't want to generate documentation:

cmake -B build -DBUILD_DOCUMENTATION=OFF

Contributing to Documentation

When adding new code:

Add documentation comments to all public APIs
Include brief descriptions for all functions and classes
Document parameters, return values, and exceptions
Provide usage examples for complex functionality
Regenerate documentation to verify: cmake --build build --target doc

Additional Resources

Version Control

The doc/ output directory is excluded from version control (.gitignore). Only the Doxyfile configuration and this guide are tracked in the repository.