API reference

The API reference is one HTML page per documented C++ class in OctoMY. QDoc, the Qt documentation generator, reads the docstrings in the source and writes the pages.

Open the API reference

What is in it

The reference covers every directory the build compiles first-party C++ from: 149 libraries, 12 applications and 32 tools. The run of 2026-10-09 produced 1,166 class pages.

Each page carries the class brief and its detailed description. A \sa QWidget in a docstring resolves to Qt's own reference page, because the generator reads Qt's installed index files.

Member lists are mostly absent, and that is measured. Of the 1,015 class pages measured on 2026-10-07, 44 carry a public-function list and 14 carry member documentation. QDoc lists a member only when that member has its own documentation block, and this project's convention makes the class block required and per-member documentation optional. A class with no documented member gets a page with its description and an empty member list.

It is generated, and it is not in git

The pages under html/ are build output. They are not tracked, and a fresh clone does not have them. Generate them with one command:

qbs build project.buildApiDocs:true --products api-reference

The run takes about seven minutes. It needs the source tree and a Qt documentation install.

The pages were tracked until 2026-10-07, and that is why they went stale: a regeneration wrote about 1,500 files into every diff, so nobody ran one. The reference was regenerated once in 6,113 commits.

Full procedure, and what to do when the run fails: Regenerate the API reference.

The run reports, so a bad run fails

Two numbers fail the build rather than writing half an answer:

Both come from a measured run, and both are declared in the build. The ceiling only ever moves down.

This matters because the generator used to report nothing. On 2026-10-07 a run produced 374 class pages where the tracked tree held 919, took 27 minutes 37 seconds, and exited 0. The cause was the configuration, not the docstrings: it handed QDoc about 10,000 vendored files it must not read.

Reading it without a browser

The pages under html/ need a browser. The same run also writes a markdown projection — one page per documented class, under classes/ — which the application's own help system carries, so a class is findable on a machine with no browser and no network.

The projection is deliberately thin: a brief, the header the class is declared in, its inheritance line, its group, a live picture when the class is a registered widget, and a link to its full page here. It carries no member list, because QDoc's index holds none for 868 of the 921 classes — a member reaches the index only when it has its own documentation block, and this project documents classes. 432 KB over 969 pages.