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

[Ben Cooksley]

On Wed, Jul 10, 2024 at 4:37 AM Nicolas Fella <nicolas.fella at gmx.de> wrote:

> Hi,
>

Hi Nicolas,


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

Logically it makes sense for us to switch documentation generation tool,
given that Qt maintains QDoc and therefore ensures it understands all of
the Qt-specific items that our code will also share, while there is no such
guarantee with Doxygen and will require work on our part. I'd also point
out that Doxygen has a habit of periodically changing the HTML it generates
- breaking custom themes like our own in the process - so this would also
mitigate that risk as well.

We will need to adapt kapidox (which helps stitch together our various
repositories) or otherwise come up with a replacement to it, but aside from
that this seems like a common sense proposal to me.


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