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

[Nicolas Fella]

On 09.07.24 18:37, Nicolas Fella wrote:
> 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?

Hi,

I implemented a proof-of-concept for converting our documentation to
qdoc and generating pages from it.

Due to the way qdoc works it makes sense to integrate the documentation
generation into the build system.
https://invent.kde.org/frameworks/extra-cmake-modules/-/merge_requests/457
adds API for this to ECM.

https://invent.kde.org/frameworks/kcoreaddons/-/merge_requests/443 shows
how it is used as well as the markup changes needed.

https://invent.kde.org/sysadmin/ci-utilities/-/merge_requests/354 adds
tooling for generating the documentation for all modules, which will
eventually become a periodic CI job.

https://invent.kde.org/nicolasfella/doc-includes contains common
configuration that is included from all modules. This could eventually
live in e.g. kapidox.

You can see it in action at
https://nicolasfella.de/docs/kcoreaddons-module.html. There's still some
minor things to be ironed out, but overall it looks promising to me.

Cheers

Nico