Code reference (Doxygen)

The firmware API and internals reference is generated by Doxygen directly from the source comments and published at /api/. This page is a signpost: it explains what the generated reference covers and how to regenerate it locally.

What the reference covers

The configuration lives in Doxyfile at the repository root. Key settings:

Setting	Value	Source
`PROJECT_NAME`	`CDC Badge OS`	`Doxyfile` line 3
`PROJECT_BRIEF`	`Firmware for the CDC Badge v1.0 hardware security key`	line 4
`OUTPUT_DIRECTORY`	`doxygen_output`	line 6
`HTML_OUTPUT`	`html`	line 49
`RECURSIVE`	`YES`	line 28
`FILE_PATTERNS`	`.h .hpp .cpp .c`	line 29
`GENERATE_HTML`	`YES`	line 46
`GENERATE_LATEX` / `GENERATE_XML`	`NO`	lines 47-48

The generated HTML is written to doxygen_output/html.

Input directories

INPUT (Doxyfile lines 9-27) covers the firmware’s own components plus main, and deliberately excludes third-party code:

Core and platform: cdc_core, cdc_hal, cdc_log, cdc_ui, cdc_views, cdc_os_ui, serial_cmd, usb_badge.
Modules: mod_ble_serial, mod_fido2, mod_gpg, mod_hid, mod_nvsedit, mod_password, mod_sao, mod_2fa, mod_vcard.
Plugin host: plugin_manager.
main.

EXCLUDE_PATTERNS (line 32) drops */test/*, */third_party/*, */managed_components/*, and */.pio/*.

Extraction and preprocessing

EXTRACT_ALL = YES, EXTRACT_STATIC = YES, EXTRACT_PRIVATE = NO (lines 35-37), so the reference documents everything except private members.
SOURCE_BROWSER = YES (line 40) cross-links declarations to source.
ESP-IDF macros are preprocessed: ENABLE_PREPROCESSING = YES, MACRO_EXPANSION = YES (lines 63-64), with PREDEFINED neutralising attributes such as EXT_RAM_BSS_ATTR and IRAM_ATTR (lines 65-70).

Generate it locally

Run Doxygen from the repository root:

doxygen Doxyfile

The HTML reference is then written to doxygen_output/html. Open the entry point in a browser:

open doxygen_output/html/index.html

Comments follow the project’s Doxygen conventions (backslash commands \brief, \param, \return), so newly documented public APIs appear in the reference automatically.