On Tue, Aug 20, 2024 at 8:07 AM Nicolas Fella <nicolas.fe...@gmx.de> wrote:
> On 09.07.24 18:37, Nicolas Fella wrote: > > Hi, > > > > 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? > > Hi, > > I implemented a proof-of-concept for converting our documentation to > qdoc and generating pages from it. > > Due to the way qdoc works it makes sense to integrate the documentation > generation into the build system. > https://invent.kde.org/frameworks/extra-cmake-modules/-/merge_requests/457 > adds API for this to ECM. > > https://invent.kde.org/frameworks/kcoreaddons/-/merge_requests/443 shows > how it is used as well as the markup changes needed. > > https://invent.kde.org/sysadmin/ci-utilities/-/merge_requests/354 adds > tooling for generating the documentation for all modules, which will > eventually become a periodic CI job. > > https://invent.kde.org/nicolasfella/doc-includes contains common > configuration that is included from all modules. This could eventually > live in e.g. kapidox. > 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 api.kde.org is based. > > You can see it in action at > https://nicolasfella.de/docs/kcoreaddons-module.html. There's still some > minor things to be ironed out, but overall it looks promising to me. > Indeed, looks quite promising. This will end up fully replacing KApiDox I assume? > > Cheers > > Nico > > > Thanks, Ben
