<div dir="ltr"><div dir="ltr">On Tue, Aug 20, 2024 at 8:07 AM Nicolas Fella <<a href="mailto:nicolas.fella@gmx.de">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">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">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">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">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">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">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">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">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">api.kde.org</a> is based.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
You can see it in action at<br>
<a href="https://nicolasfella.de/docs/kcoreaddons-module.html" rel="noreferrer" target="_blank">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 class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Cheers<br>
<br>
Nico<br>
<br>
<br></blockquote><div><br></div><div>Thanks,</div><div>Ben </div></div></div>