apidocs

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

apidocs

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. Producing the pages is building, and the build does that: the api-reference product invokes QDoc on the file this tool writes.

Usage

apidocs config --repo <dir> --out <file>
apidocs check  --repo <dir>
apidocs coverage --repo <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
coverage Counts, per library in src/libs, the .cpp files without a \class block. Writes nothing
Option Meaning
--repo <dir> The repository root. Default: the current folder
--out <file> With config: the generated configuration to write
--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

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

$ qbs run -p 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

$ qbs run -p 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. 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

In this section
Topics
reference tools api qdoc build
See also