Next-gen API documentation for QML types
The way we present API documentation for QML types on api.kde.org is not great.
This comes largely down to the fact that we shoehorn it into the existing C++-oriented class documentation system.
This has several problems:
- It's not clear in the documentation site whether a type is C++ API, QML API, or both
- We don't show useful information like the required imports
- For types that are C++-defined but exposed to QML we show lots of uninteresting noise in the functions list, like property getter/setters
- We don't show things like attached properties properly
- Generally documenting QML types like C++ classes doesn't work very well
Some of these things can be improved by e.g. hiding more functions or adding more text, but I think we are hitting the limits of what our current approach can deliver. What we need is proper, QML-native documentation pages in our site that properly describe QML-specific concepts, similar to what Qt offers for its QML types.
How can we achieve that?
One possible avenue could be using qdoc since that has first-class support for QML types. The challenge here would be how it would integrate with the existing doxygen-based system.
Another approach that came to my mind would be writing some new tooling that generates custom documentation pages from existing information and integrates that into api.kde.org somehow. I'm not sure how feasible such integration is or how it could look like, but I see at least a viable path for generating such sites.
Thanks to the new developments in QML tooling we will have qmltypes files for all our QML modules. These qmltypes files contain almost all of the structural type information that is relevant for C++-defined QML types (properties, signals, functions etc). The only thing that's missing is the actual documentation comments for those, but these are available from doxygen, so linking the two should be possible. From that information one could generate a nice documentation site. Unfortunately we don't have qmltypes files for QML-defined types. Something that could potentially work is using the existing doxyqml to turn the QML into C++, then using qmltyperegistrar to turn that into qmltypes. Or something based on qmldom.
Writing such a tool and integrating the result into api.kde.org would be a quite large task, but it has the potential to massively improve the quality of our documentation