The state of our API documentation and what to do about it

[Nicolas Fella]

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