<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<div class="moz-cite-prefix">On 20.08.24 13:33, Ben Cooksley wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CA+XidOF9TaCDOEy7O=eCHVFPAOV2ESynOSAeZRWizj9vaJELtQ@mail.gmail.com">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<div dir="ltr">
<div dir="ltr">On Tue, Aug 20, 2024 at 8:07 AM Nicolas Fella
<<a href="mailto:nicolas.fella@gmx.de"
moz-do-not-send="true" class="moz-txt-link-freetext">nicolas.fella@gmx.de</a>>
wrote:<br>
</div>
<div class="gmail_quote">
<blockquote class="gmail_quote"
style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On
09.07.24 18:37, Nicolas Fella wrote:<br>
> Hi,<br>
><br>
> while reviewing our API documentation I noticed an
increasing amount of<br>
> brokenness in it. Not even in the content, but the way
it is presented.<br>
><br>
> Doxygen seems to struggle to properly parse and
document some new-ish Qt<br>
> features:<br>
><br>
> - It doesn't parse signals declared with Q_SIGNAL (as
opposed to<br>
> Q_SIGNALS:) as such, so there will be a stray
"Q_SIGNAL" in the page and<br>
> the function not marked as a signal. This can be seen
e.g. at<br>
> <a
href="https://api.kde.org/frameworks/kcmutils/html/classKPluginModel.html#a6c3d36e9c38730cc1e6f6697d2253600"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://api.kde.org/frameworks/kcmutils/html/classKPluginModel.html#a6c3d36e9c38730cc1e6f6697d2253600</a><br>
><br>
><br>
> - It doesn't handle the declarative type registration
macros<br>
> (QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON etc)
correctly, so they<br>
> randomly show up in the documentation. See e.g.<br>
> <a
href="https://api.kde.org/frameworks/kirigami/html/classKirigami_1_1Platform_1_1IconSizes.html#ad87aa092b90a9d8a2cb2464775c2e370"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://api.kde.org/frameworks/kirigami/html/classKirigami_1_1Platform_1_1IconSizes.html#ad87aa092b90a9d8a2cb2464775c2e370</a><br>
><br>
><br>
> Then there's the general problem with doxygen not
natively supporting<br>
> QML. We work around this with doxyqml, which translates
QML files into<br>
> C++-ish files that then get processed by doxygen. That
works okay, but<br>
> is far from ideal. For example:<br>
><br>
> - C++ types and QML types are listed side-by-side on
the website, with<br>
> no clear distinction between those<br>
><br>
> - QML types that are defined in C++ aren't properly
indicated as QML API<br>
> and their documentation shows lots of irrelevant
functions like property<br>
> getters/setters<br>
><br>
> - Some property types are not displayed correctly, e.g.
list<T.Action><br>
> is displayed as listTAction:<br>
> <a
href="https://api.kde.org/frameworks/kirigami/html/classCard.html"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://api.kde.org/frameworks/kirigami/html/classCard.html</a><br>
><br>
> - QML-specific concepts like attached properties are
not supported<br>
><br>
> - Types that are usable from QML *and* C++ aren't
marked as such<br>
><br>
> - alias properties don't have their type in the
documentation<br>
><br>
> - The page doesn't show the QML import name to be used
to import the type<br>
><br>
> Generally browsing the documentation for Qt's own QML
types feels vastly<br>
> better than e.g. Kirigami's documentation.<br>
><br>
> What can we do about this? While some of these problems
could likely be<br>
> addressed by better markup or upstream work on doxygen
and doxyqml I'm<br>
> afraid it will always be an uphill battle to get
doxygen to nicely<br>
> document Qt-specific concepts. From my own experience I
can say that<br>
> contributing even small improvements to our
documentation markup doesn't<br>
> feel rewarding given the overall poor state of the
system.<br>
><br>
> Qt maintains its own documentation tooling, qdoc, which
is<br>
> (unsurprisingly) much better at documenting Qt-specific
concepts and<br>
> QML. qdoc is actively maintained, well documented, and
in my experience<br>
> pleasant to use. From past discussions I gather that
the primary<br>
> objection to qdoc is that it requires documentation
comments to be in<br>
> the source files instead of the headers. For this
reason I am working on<br>
> a qdoc patch to allow the documentation to be contained
in header files:<br>
> <a
href="https://codereview.qt-project.org/c/qt/qttools/+/574401"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://codereview.qt-project.org/c/qt/qttools/+/574401</a><br>
><br>
> With this in mind I propose that we migrate out API
documentation from<br>
> doxygen to qdoc. Since the markup is using slightly
different<br>
> syntax/keywords there will be some work involved, but
the concepts<br>
> usually map so that work is at least semi-automatable.
While there will<br>
> be a medium amount of manual labor involved I firmly
believe the result<br>
> will be worth it by having much better documentation
especially for QML<br>
> types.<br>
><br>
> Thoughts on my proposal?<br>
<br>
Hi,<br>
<br>
I implemented a proof-of-concept for converting our
documentation to<br>
qdoc and generating pages from it.<br>
<br>
Due to the way qdoc works it makes sense to integrate the
documentation<br>
generation into the build system.<br>
<a
href="https://invent.kde.org/frameworks/extra-cmake-modules/-/merge_requests/457"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://invent.kde.org/frameworks/extra-cmake-modules/-/merge_requests/457</a><br>
adds API for this to ECM.<br>
<br>
<a
href="https://invent.kde.org/frameworks/kcoreaddons/-/merge_requests/443"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://invent.kde.org/frameworks/kcoreaddons/-/merge_requests/443</a>
shows<br>
how it is used as well as the markup changes needed.<br>
<br>
<a
href="https://invent.kde.org/sysadmin/ci-utilities/-/merge_requests/354"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://invent.kde.org/sysadmin/ci-utilities/-/merge_requests/354</a>
adds<br>
tooling for generating the documentation for all modules,
which will<br>
eventually become a periodic CI job.<br>
<br>
<a href="https://invent.kde.org/nicolasfella/doc-includes"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://invent.kde.org/nicolasfella/doc-includes</a>
contains common<br>
configuration that is included from all modules. This could
eventually<br>
live in e.g. kapidox.<br>
</blockquote>
<div><br>
</div>
<div>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 <a href="http://api.kde.org" moz-do-not-send="true">api.kde.org</a>
is based.</div>
</div>
</div>
</blockquote>
<p>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. <br>
</p>
<p>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).<br>
</p>
<blockquote type="cite"
cite="mid:CA+XidOF9TaCDOEy7O=eCHVFPAOV2ESynOSAeZRWizj9vaJELtQ@mail.gmail.com">
<div dir="ltr">
<div class="gmail_quote">
<blockquote class="gmail_quote"
style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
You can see it in action at<br>
<a
href="https://nicolasfella.de/docs/kcoreaddons-module.html"
rel="noreferrer" target="_blank" moz-do-not-send="true"
class="moz-txt-link-freetext">https://nicolasfella.de/docs/kcoreaddons-module.html</a>.
There's still some<br>
minor things to be ironed out, but overall it looks
promising to me.<br>
</blockquote>
<div><br>
</div>
<div>Indeed, looks quite promising. This will end up fully
replacing KApiDox I assume?</div>
</div>
</div>
</blockquote>
<p>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.</p>
</body>
</html>