On Wed, Jul 10, 2024 at 4:37 AM Nicolas Fella <nicolas.fe...@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
