API reference

The API reference is generated by Doxygen from the public headers: open the API reference. The headers themselves remain the source: what you read there is what the header says, nothing more.

How it is organised

You look for	Where it is
a module	Namespaces: every core is shuffle::<module> (shuffle::dsp, shuffle::cues, …); adapters use a namespace named after their module
what a component is for and the rules it enforces	the file page of its header: the purpose block at the top of the header is the file description, and it is repeated on the class named like the file
ports (what a backend implements)	headers under core/<module>/include/shuffle/<module>/ports/
fakes of the ports, for tests	headers under .../testing/
contract suites every port implementation passes	headers under core/<module>/contracts/
adapters (ports on the OS, miniaudio, libremidi, codecs, plugin formats)	headers under adapters/; the JUCE and Tracktion adapters are documented in shuffle_juce

Each function carries the comment written above it in the header. Two marks make the threading rules visible:

• Thread: labels say which thread may call a function (“Thread: control”, “Thread: audio”, “Thread: any”). A function without one follows the rule of its header’s purpose block.
• real-time safe marks every function declared SHUFFLE_RT: noexcept, no allocation, no lock, no I/O, checked by the compiler (decision 0019). Only these may run on the audio thread.

Requirement IDs such as EN-R84 and paths such as specs/engine.md link to the specification, so a function leads to the behaviour it implements.

Only the public surface is shown: private members, detail namespaces, sources and tests are left out. Undocumented data members and enumerators are listed without a description.

Building it locally

From the repository root, with Doxygen (1.9 or later) and Python 3 on the path:

doxygen docs/api/Doxyfile                       # -> docs/api/html/index.html
python tools/api_docs.py check docs/api/warnings.log
quarto render docs                              # the site, with the reference under api/html/

Every header goes through tools/api_docs.py filter, which changes comments only (and keeps every line where it was, so warnings point at the real file): it turns the // purpose block into the file description, // comments above declarations into documentation, requirement IDs into links, “Thread:” into a label, and SHUFFLE_RT into the real-time safe tag.

The check step is the gate CI runs: it fails on any Doxygen warning in a module whose comments are complete (rule 8 of tools/check_repo.py), and only counts “not documented” warnings for members rule 8 does not ask a comment of (data members, enumerators, trivial accessors under a shared comment).

Keeping it complete

python tools/check_repo.py (rule 8) requires, in every public header, the SPDX lines followed by a purpose block, and a comment above every public function declaration. python tools/check_repo.py --comments core/<module>/ lists what is missing in one module. A module still being documented is listed in COMMENTS_PENDING in tools/check_repo.py.

The same comments feed llms-full.txt, the digest of every module for language models (python tools/llms_full.py).