Hi, while reviewing our API documentation I noticed an increasing amount of brokenness in it. Not even in the content, but the way it is presented.
Doxygen seems to struggle to properly parse and document some new-ish Qt features: - It doesn't parse signals declared with Q_SIGNAL (as opposed to Q_SIGNALS:) as such, so there will be a stray "Q_SIGNAL" in the page and the function not marked as a signal. This can be seen e.g. at https://api.kde.org/frameworks/kcmutils/html/classKPluginModel.html#a6c3d36e9c38730cc1e6f6697d2253600 - It doesn't handle the declarative type registration macros (QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON etc) correctly, so they randomly show up in the documentation. See e.g. https://api.kde.org/frameworks/kirigami/html/classKirigami_1_1Platform_1_1IconSizes.html#ad87aa092b90a9d8a2cb2464775c2e370 Then there's the general problem with doxygen not natively supporting QML. We work around this with doxyqml, which translates QML files into C++-ish files that then get processed by doxygen. That works okay, but is far from ideal. For example: - C++ types and QML types are listed side-by-side on the website, with no clear distinction between those - QML types that are defined in C++ aren't properly indicated as QML API and their documentation shows lots of irrelevant functions like property getters/setters - Some property types are not displayed correctly, e.g. list<T.Action> is displayed as listTAction: https://api.kde.org/frameworks/kirigami/html/classCard.html - QML-specific concepts like attached properties are not supported - Types that are usable from QML *and* C++ aren't marked as such - alias properties don't have their type in the documentation - The page doesn't show the QML import name to be used to import the type Generally browsing the documentation for Qt's own QML types feels vastly better than e.g. Kirigami's documentation. What can we do about this? While some of these problems could likely be addressed by better markup or upstream work on doxygen and doxyqml I'm afraid it will always be an uphill battle to get doxygen to nicely document Qt-specific concepts. From my own experience I can say that contributing even small improvements to our documentation markup doesn't feel rewarding given the overall poor state of the system. Qt maintains its own documentation tooling, qdoc, which is (unsurprisingly) much better at documenting Qt-specific concepts and QML. qdoc is actively maintained, well documented, and in my experience pleasant to use. From past discussions I gather that the primary objection to qdoc is that it requires documentation comments to be in the source files instead of the headers. For this reason I am working on a qdoc patch to allow the documentation to be contained in header files: https://codereview.qt-project.org/c/qt/qttools/+/574401 With this in mind I propose that we migrate out API documentation from doxygen to qdoc. Since the markup is using slightly different syntax/keywords there will be some work involved, but the concepts usually map so that work is at least semi-automatable. While there will be a medium amount of manual labor involved I firmly believe the result will be worth it by having much better documentation especially for QML types. Thoughts on my proposal? Cheers Nico
