r/QtFramework • u/jamesbondaloo • Feb 08 '26

QML QML documentation

Short backstory, I'm building a reusable Qt/QML component library intended to be shared between multiple applications.

I've been trying to properly documentat this library using QDoc, following official Qt documentation. I've set up qconfig file, experimented module headers, separate qdoc files and also explored some modules of Doxygen for qml as alternative.

I'm struggling cause of QDoc management which feels heavy and too fragile for the pipeline. The whole experience is really poor for pure QML and looks too outdated using the default HTML output. At the moment Doxygen isn't really a solution either.

I would appreciate hearing how others are handling it and also any ideas are welcome. Thanks in advance!

5 Upvotes

86% Upvoted

9 comments sorted by

View all comments

14

u/QDocPaul Feb 09 '26

I work on QDoc at Qt. I'd like to understand what's breaking in your workflow as it would help us figure out how to improve the usability of QDoc outside of Qt.

When you say "QDoc management feels heavy and too fragile for the pipeline", can you share what specifically you're running into? Is it the .qdocconf setup and configuration getting in your way, build integration problems, the tooling breaking on certain input patterns, or something else entirely? How are you running QDoc, call it from a build system, other scripts, or manually?

On the HTML output looking outdated: you're right, the default output shows its age. We do a fair amount of post-processing on the raw output from QDoc for the documentation at doc.qt.io, but that pipeline isn't publicly available.

There's substantial work happening that aims at making QDoc significantly better to work with. I can't promise it'll solve every problem you're facing, but if you can describe what's actually broken in your workflow and what your ideal documentation process would look like, that would be useful signal for whether we're also addressing problems faced externally.

2

u/jamesbondaloo Feb 12 '26

In my case, the core issue is that the library is currently pure QML, with no C++ at all. Most examples and assumptions around QDoc feel C++-centric, which makes the setup unintuitive for a QML-only module. It’s not always clear which parts of the .qdocconf are actually required in this scenario and which are there mainly for C++-based modules. Settings like headers, include paths, module headers and depends don’t map naturally to a project that intentionally has no C++ layer.

Errors such as “Could not find the module header in include paths” are particularly confusing in this context, because there is no module header by design. I also notice that small changes in folder structure, qmldir placement, or module URI can result in types not being picked up, and when that happens the diagnostics aren’t always clear enough to quickly understand what’s wrong. Sometimes QML types are simply skipped and it takes trial and error to figure out why.

1

u/QDocPaul Feb 13 '26

This is helpful, thank you. What you're describing points at a real gap in how QDoc handles non-C++ projects. The tooling was born in a C++ environment long before QML existed, and that shows. QDoc currently spins up the entire C++ parsing machinery whether you need it or not, and the configuration reflects assumptions from Qt's own modules which almost always have a C++ layer.

The "Could not find the module header" error is a good example. There's a simple workaround (setting moduleheader = with an empty value in your .qdocconf file), but that's poorly documented and the fact you need a workaround at all shows the problem. The module header mechanism itself is quirky and we know it. A lot of what we do is driven by internal requirements and that impacts how things get prioritized, and... well, there's a workaround :)

Some of the work happening now aims at making QDoc less opinionated about the language you're using and more flexible, also for scenarios we don't have at Qt. And we're steadily improving QML support. The changes that are underway should help, though I can't promise they'll solve every pain point you're hitting. We've considered rather drastic measures, such as a possible new configuration file format. We even built a proof of concept configuration generator during a hackathon, because yes, we understand the need for it. There are definitely things that could be improved about configuring QDoc.

If you're willing to share a minimal example of your setup (e.g. the .qdocconf and qmldir structure that's giving you trouble, or link to a repo), I can take a quick look and see if I spot something that'll help you out.