octomy::apidocs::ConfigPlan

Derives the directory lists QDoc needs from the tree, so that the lists cannot disagree with the tree.

Detailed description

Why a list is derived and not written

The tracked configuration listed 100 library directories by hand. It drifted in both directions at once: it reached 99 of the tree's 193 qbs product roots, and it handed QDoc about 10,000 vendored files, which cost 545 class pages and 24 minutes of every run. Both halves of that drift are invisible, because QDoc writes a smaller tree and exits 0.

A list derived from the tree cannot drift. The rule has no judgment in it:

• A directory is a qbs product root when it holds lib.qbs, app.qbs or tool.qbs. That marker is what the build's own probes read, so the set is exactly what the build compiles.
• A directory is vendored when a prefix in integration/lint/vendored-paths.txt matches it. That file is the tree's single answer to "what did we not write".

A product root enters the plan when it holds first-party C++. One root with no first-party source is not a defect — four Khronos libraries and one tool have none — so an empty root is reported and left out.

Reading the vendored list against the disk

The prefix list is also checked the other way: a directory named *-src or vendor* that no prefix covers is reported. That gap is how llvm-src and rl-tools-src reached every guard in the tree 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.

Walking with QDir, and the one entry name it refuses

The walk reads directory names through QDir, which hands back QString with no encoding conversion. It rejects an entry name that is empty or carries a path separator or a colon, because a sweep once listed a real directory as the empty string and acted on the result. Nothing here deletes anything, and the check costs one comparison per entry.

The rule and the generated configuration are specified in content/doc/internal/specs/api-reference/architecture.md, §APD-A1 and §APD-A2.

That reference is plain prose on purpose. QDoc's see-also command resolves API symbols, and a repository path is not one, so a path there becomes a missing-comma warning plus one unresolved link per word. Commit a946c3336d removed that exact shape from this tree once already, and this block reintroduced it for one build before the warning count caught it.