The state of our API documentation and what to do about it
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 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? Cheers Nico
Re: The state of our API documentation and what to do about it
El dimarts, 9 de juliol del 2024, a les 18:37:16 (CEST), Nicolas Fella va escriure: > 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#a6c3d36e > 9c38730cc1e6f6697d2253600 > > - 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_1Ic > onSizes.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 > 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 Without having fully read the email this was going to be my question. If this gets fixed, I "don't care" if we use doxygen or qdoc. Cheers, Albert > > 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? > > Cheers > > Nico
Re: The state of our API documentation and what to do about it
Hi Nicolas, I couldn't find according tickets in Doxygen's issue tracker. I looked for Q_SIGNAL, QML_ELEMENT, QML_NAMED_ELEMENT, and QML_SINGLETON. I know they have 1,7k open issues and it might not be their highest priority. I still would prefer to let Doxygen know what we as their users would like to get. Maybe we can offer patches or pay someone to fix the issues for us? I mean, Doxygen is THE standard to generate API documentations from annotated inline comments. My distribution offers a qdoc, it will work for me. Bye Christoph
KDE Missing Libraries
These 19 packages are missing from my KDE Plasma 5.23 Slackware 15.0_64 system. kactivitymanagerd-pluginsrc, krunnerrc, kuriikwsfiltersrc, baloofilerc, plasmaanotifyrc, kaccessrc, plasmaUserFeedback, touchpadxlibinputrc, kgammarc, device_automounter-kcmrc, kgammarc, device_automounter_kcmrc, kded_device_automounterrc, konsolesshconfig, breezere, kcmfonts, klaunchrc, kwinrc (DE effects), and kactivitymanager-switcher I meticulously went through the kde files on GitHub to find out what was missing and why I couldn't select a new global theme. The Icons on my choice and other things would not stick after logging out and logging back in again. This is the website where I found those kde-lib's https://github.com/shalva97/kde-configuration-files Any help and ideas in this matter would be greatly appreciated. I want to learn. Thanks in advance.
Re: The state of our API documentation and what to do about it
On Wed, Jul 10, 2024 at 4:37 AM Nicolas Fella 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 > 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
Changing dependencies for a project
I have just changed the dependencies for KAlarm (removed Canberra, added libvlc and libvlccore), but after committing the changes, the build fails on invent.kde.org. I've changed everything I can find in the KAlarm repository relating to the dependencies, so is there something else I need to do to set up the new dependencies? -- David Jarvie. KDE developer, KAlarm author.
Re: The state of our API documentation and what to do about it
> Thoughts on my proposal? +1000 Do you have a branch where you're testing this along with the qdoc patch? David
Re: Changing dependencies for a project
El dimarts, 9 de juliol del 2024, a les 22:12:40 (CEST), David Jarvie va escriure: > I have just changed the dependencies for KAlarm (removed Canberra, added > libvlc and libvlccore), but after committing the changes, the build fails on > invent.kde.org. In the future probably helps if you do similar (or all) your changes as Merge Requests instead of directly committing. This way you would have found this issue earlier and we would not end up with a non compiling CI. Cheers, Albert > I've changed everything I can find in the KAlarm repository > relating to the dependencies, so is there something else I need to do to > set up the new dependencies?
KDE Gear projects with failing CI (master) (9 July 2024)
Please work on fixing them, otherwise i will remove the failing CI jobs on their 4th failing week, it is very important that CI is passing for multiple reasons. Good news: 4 repositories have been fixed Bad news: 1 repository is still failing, 3+ repositories have started failing kio-extras - 3rd week * https://invent.kde.org/network/kio-extras/-/pipelines/730935 * Windows build fails to build kio_sftp * Potential fix at https://invent.kde.org/network/kio-extras/-/merge_requests/355 kalarm - NEW * https://invent.kde.org/pim/kalarm/-/pipelines/731010 * New dependencies where introduced the wrong way kdenlive - NEW * https://invent.kde.org/multimedia/kdenlive/-/pipelines/730933 * craft_windows_qt6_mingw64 timed out? craft_macos_qt6_x86_64 is broken * https://invent.kde.org/graphics/okular/-/pipelines/730930 * https://invent.kde.org/multimedia/kdenlive/-/pipelines/730933 * https://invent.kde.org/network/kdeconnect-kde/-/pipelines/730936 * Volker pointed to https://invent.kde.org/packaging/craft-blueprints-kde/-/merge_requests/933 as culprit Should it be reverted? Cheers, Albert
Re: Changing dependencies for a project
On Tuesday, 9 July 2024 23:47:30 BST Albert Astals Cid wrote: > El dimarts, 9 de juliol del 2024, a les 22:12:40 (CEST), David Jarvie va > > escriure: > > I have just changed the dependencies for KAlarm (removed Canberra, added > > libvlc and libvlccore), but after committing the changes, the build fails > > on invent.kde.org. > > In the future probably helps if you do similar (or all) your changes as > Merge Requests instead of directly committing. > > This way you would have found this issue earlier and we would not end up > with a non compiling CI. If I'd created a merge request, it would presumably have just sat there unmergeable because of the missing CI dependency. How does a new dependency get added to the CI? > > I've changed everything I can find in the KAlarm repository > > relating to the dependencies, so is there something else I need to do to > > set up the new dependencies? -- David Jarvie. KDE developer, KAlarm author.
Re: KDE Gear projects with failing CI (master) (9 July 2024)
On Tuesday, 9 July 2024 23:57:09 BST Albert Astals Cid wrote: > Please work on fixing them, otherwise i will remove the failing CI jobs on > their 4th failing week, it is very important that CI is passing for multiple > reasons. > > Good news: 4 repositories have been fixed > > > Bad news: 1 repository is still failing, 3+ repositories have started > failing > kalarm - NEW > * https://invent.kde.org/pim/kalarm/-/pipelines/731010 > * New dependencies where introduced the wrong way I've already asked on this list how to add the CI dependency, but I need an answer to know how to fix this. -- David Jarvie. KDE developer, KAlarm author.
Re: Changing dependencies for a project
On Wednesday, 10 July 2024 01:51:16 CEST, David Jarvie wrote: On Tuesday, 9 July 2024 23:47:30 BST Albert Astals Cid wrote: El dimarts, 9 de juliol del 2024, a les 22:12:40 (CEST), David Jarvie va escriure: ... If I'd created a merge request, it would presumably have just sat there unmergeable because of the missing CI dependency. How does a new dependency get added to the CI? I've changed everything I can find in the KAlarm repository relating to the dependencies, so is there something else I need to do to set up the new dependencies? You can a) file a sysadmin ticket or b) create a MR for https://invent.kde.org/sysadmin/ci-images/ adding the dependency to the images. It seems, judging from a quick look, that vlc is missing for the qt6 variants because it pulls in qt5. Regards, Heiko
Re: Changing dependencies for a project
Hi, To paraphrase Captain Tsubasa "the CI is your friend". If there was a merge request, the build would have failed and you still would have sent a mail here to ask how to add the dependency :). Even for smaller changes, it's always interesting to have the CI run because it's quite quick and can find small issues that can be avoided (for example, if a file is added, it could be easy to miss to add the licence, the reuse job will fail and in a wonderful world, the commit where the file has been added would be amended to add the licence and we will have a clean history. Or if a xml is not correctly formatted for example). Heiko answered you for the process to add the dependency. And thanks for the change, it's always nice to have up-to-date code! Cheers, Johnny Le mer. 10 juil. 2024 à 01:52, David Jarvie a écrit : > > On Tuesday, 9 July 2024 23:47:30 BST Albert Astals Cid wrote: > > El dimarts, 9 de juliol del 2024, a les 22:12:40 (CEST), David Jarvie va > > > > escriure: > > > I have just changed the dependencies for KAlarm (removed Canberra, added > > > libvlc and libvlccore), but after committing the changes, the build fails > > > on invent.kde.org. > > > > In the future probably helps if you do similar (or all) your changes as > > Merge Requests instead of directly committing. > > > > This way you would have found this issue earlier and we would not end up > > with a non compiling CI. > > If I'd created a merge request, it would presumably have just sat there > unmergeable because of the missing CI dependency. How does a new dependency > get added to the CI? > > > > I've changed everything I can find in the KAlarm repository > > > relating to the dependencies, so is there something else I need to do to > > > set up the new dependencies? > > -- > David Jarvie. > KDE developer, KAlarm author.
