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

[Nicolas Fella]

On 20.08.24 13:33, Ben Cooksley wrote:
> On Tue, Aug 20, 2024 at 8:07 AM Nicolas Fella <nicolas.fella at gmx.de>
> wrote:
>
>     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.
>
>
> For both sysadmin/ci-utilities and doc-includes another potential
> place for this to live would be websites/api-kde-org which is where
> the existing logic to build api.kde.org <http://api.kde.org> is based.

The actual website generation could also live in websites/api-kde-org. I
added it to ci-utilities because it uses the python stuff in there for
the package registry, but that could be solved differently.

doc-includes or however it ends up being named should probably be a
standalone thing similar to kapidox since it will also be relevant for
people generating docs locally or as part of distro builds (for QCH).

>     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.
>
>
> Indeed, looks quite promising. This will end up fully replacing
> KApiDox I assume?

That's a good question. Ideally we would only have one way of doing API
docs. Converting all of Frameworks is something that should be doable
fairly quickly. However there's also a number of other documented
libraries that would need converting too. Not sure how long that would
take. We may or may not want to consider some sort of hybrid solution
that integrates the old and new approach.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-devel/attachments/20240820/c35a617f/attachment-0001.htm>