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

[Ben Cooksley]

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 is based.


>
> 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?


>
> Cheers
>
> Nico
>
>
>
Thanks,
Ben
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-devel/attachments/20240820/a40c21da/attachment.htm>