<div dir="ltr"><div dir="ltr">On Wed, Jul 10, 2024 at 4:37 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">Hi,<br></blockquote><div><br></div><div>Hi Nicolas,</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>
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>
- 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>
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. </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Thoughts on my proposal?<br></blockquote><div><br></div><div>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.</div><div> </div><div>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.</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>Cheers,</div><div>Ben </div></div></div>