apidocs

Derives the directory lists QDoc needs, and refuses a configuration that would read a vendored tree

apidocs decides what QDoc may read. It writes the generated half of the API reference configuration, and it verifies the inputs that configuration is built from.

It does not run QDoc for the reference. Producing the pages is building, and the build does that: kiln apidocs invokes QDoc on the file this tool writes. Only record runs QDoc, to make the expected output of a test fixture.

Usage

apidocs config   --repo <dir> --out <file>
apidocs check    --repo <dir>
apidocs project  --repo <dir> --index <octomy.index> --docbook <dir> --out <api root>
apidocs coverage --repo <dir>
apidocs parity   --repo <dir> --qdoc <dir> --engine <dir>
apidocs record   --repo <dir> --case <dir> --qdoc <program> --qt-docs <dir>
Mode What it does
config Writes the generated configuration to --out. This is what the build runs before QDoc
check Verifies the same inputs and writes nothing. Prints the number of roots read to standard output
project Turns QDoc's DocBook pages and its index into the markdown reference under --out
coverage Counts, per library in src/libs, the .cpp files without a \class block. Writes nothing
parity Compares QDoc's output with the doc engine's, and prints each difference. Exits 1 on any difference
record Runs a QDoc on a test fixture and keeps its output in the fixture's expected/ folder
Option Meaning
--repo <dir> The repository root. Default: the current folder
--out <file> With config: the generated configuration to write. With project: the API root
--qdoc <path> With parity: QDoc's output folder, which holds docbook/ and the index. With record: the QDoc program
--engine <dir> With parity: the doc engine's output folder
--qdoc-warnings <file> With parity: a file with QDoc's warnings, such as the log of kiln apidocs. Default: warnings.txt in the QDoc folder
--qdoc-root <dir>, --engine-root <dir> With parity: the root that each side's paths start with. Default: --repo
--case <dir> With record: the fixture folder, which holds src/
--qt-docs <dir> With record: Qt's documentation folder, where QDoc reads the Qt indexes
--define <name> With record, once for each: a define that QDoc's parse sees
--quiet Errors only
--verbose Every root left out, and every directory excluded, one per line
--help The usage above
--version The commit this binary was built from

Build it with kiln build src/tools/apidocs. The examples below run it from debug/apidocs/apidocs, its path with no output.dir (Invoking a tool).

What it derives, and from what

The tool applies one rule with no judgment in it:

A directory is first-party when the build compiles C++ from it, and no prefix in integration/lint/vendored-paths.txt matches it.

Both inputs are already in the tree, and neither is a list this tool keeps:

  • The product markers. A directory holding lib.qbs, app.qbs or tool.qbs is a qbs product root. That marker is what the build's own probes read, so the tool finds exactly what the build compiles.
  • integration/lint/vendored-paths.txt. The repository's single answer to "what did we not write", shared with three other guards.

A product root enters the configuration when it holds first-party C++. A root with none is reported and left out, which is not a defect: four Khronos libraries and one tool have no first-party source at all.

Qt's own include directories come from QLibraryInfo, so no Qt path is written down anywhere.

Reading check

$ debug/apidocs/apidocs check --repo .
188 product roots read, 5 with no first-party C++, 14 vendored directories excluded
warninglimit 1438, enabled, one spurious pattern
188

The last line is the answer on standard output. The two above it are the summary, on standard error.

Add --verbose to see which roots were left out and which directories were excluded, one per line.

Reading coverage

$ debug/apidocs/apidocs coverage --repo .
Library                  Remaining   Total
libllvm                       4538    4541
libconstruct                   381     399
...

One row for each library that has a .cpp file without a \class block. The library with the most files to document comes first. A file counts as documented when its text holds \class anywhere. Vendored directories are counted too. The table goes to standard output, and a one-line total goes to standard error.

coverage is a report, not a check: it exits 0 whatever the count. It exits 4 when --repo holds no src/libs.

coverage replaced content/doc/scripts/check_docs.sh on 2026-10-11 (script-ports §SCP-D-14). That script stopped at the first library with no documented file, so it printed one row.

When it fails

Exit Cause
0 The plan is sound
1 A directory named *-src or vendor* is not covered by vendored-paths.txt, or the tracked configuration broke a rule
2 The command line was wrong. Nothing was attempted
3 vendored-paths.txt is empty, or holds a prefix that is not a valid expression
4 The repository root is not one, or Qt reports no headers directory. With coverage: there is no src/libs

Exit 1 on an uncovered vendored tree is the important one. QDoc builds one precompiled header from every header directory it is given, so a single vendored tree in the parse costs hundreds of class pages and the run still exits 0. The tool refuses to write a configuration that would do that. The fix is one line in vendored-paths.txt.

That gap is not hypothetical. llvm-src and rl-tools-src sat outside that file for months. Both are fetched on demand, so a checkout that never fetched has no files there, and an absent tree and an excluded tree produce the same clean report.

Where its logic lives

The units are in src/libs/libapidocs/apidocs/ConfigPlan.{hpp,cpp}, beside the tool, so the tool and its tests build one set of objects. main.cpp takes argv and nothing else.

Two suites cover it. testApidocsConfigPlan drives the rule, and the coverage count, over synthetic trees in a temporary directory. testApiReferenceConfig is a guard: it asserts the same rule against this repository, and it runs in every test run.

See also

Reading parity

parity answers one question: does the doc engine write the same reference as QDoc? It compares the two output folders at four levels:

Level The same when
L1 pages The two folders hold the same DocBook page names
L2 content The projection makes the same markdown from each pair of pages
L3 index The index entries that the projection reads are equal
L4 warnings The two lists of file, line and message are equal

A fixture compared with itself, as the suite testApidocsParity does:

$ debug/apidocs/apidocs parity --repo . --qdoc test/fixtures/doc-engine/warnings/expected --engine test/fixtures/doc-engine/warnings/expected --qdoc-root @ROOT@ --engine-root @ROOT@
pages: QDoc 4, engine 4; warnings: QDoc 7, engine 7
differences: L1 pages 0, L2 content 0, L3 index 0, L4 warnings 0

Each difference follows on a line of its own, with its level, its kind, the page or the warning, and what differs.

Recording a fixture

A fixture of the doc engine is a folder under test/fixtures/doc-engine/ with a small src/ tree. record copies it into a scratch checkout with the tracked QDoc configuration, runs the QDoc you name, and writes the DocBook pages, octomy.index, warnings.txt and qdoc-version.txt to the fixture's expected/ folder. Every path of the scratch checkout becomes @ROOT@, so the fixture holds no path of your machine. Use the QDoc that kiln apidocs runs:

debug/apidocs/apidocs record --repo . --case test/fixtures/doc-engine/one-class --qdoc ~/Qt/6.10.1/gcc_64/bin/qdoc --qt-docs ~/Qt/Docs/Qt-6.10.1
In this section
Topics
reference tools api qdoc build
See also