API documentation porting sprint

Farid Abdelnour — Wed, 13 Nov 2024 00:00:00 +0000

It was once said over the grapevine that: "Our C++ API documentation has some issues, our QML API documentation has a lot of issues."

And it was true, but that is to change soon! As you might know, there is an ongoing effort to port our documentation from Doxygen to QDoc, and you can help with that.

This is a task that has been adopted by the Streamlined Application Development Experience championed by Nicolas Fella and Nate Graham as part of the KDE Goals initiative.

We would like to invite you to join our porting sprint effort to finish this task. On November 14th at 1PM UTC, we'll be hanging out in the Matrix room working on this. Hope to see you there.

Some prerequisites:

Ability to use a terminal
Extra disk space (30GB minimum)
Some familiarity with APIs

Check out the instructions prepared by Thiago Sueto on how to get started porting a project to QDoc.

unique_ptr difference between libstdc++ and libc++ crashes your application

David Faure — Sat, 20 Feb 2021 00:00:00 +0000

Thanks to the KDE FreeBSD CI, which runs our code on top of libc++, we discovered an interesting difference between libstdc++ and libc++'s implementation of unique_ptr. This is quite unexpected, and the actual result for users is even more unexpected: it can lead to crashes in specific situations. This happens when a widget -- using unique_ptr for its d pointer, as is customary these days -- installs an event filter. That event filter will be triggered during destruction of child widgets (at least for the QEvent::Destroy event, I've also seen it with QEvent::Leave events for instance). And, depending on how the event filter is written, it might use the d pointer of the widget, possibly before checking the event type. That's where it gets interesting: the libc++ implementation of unique_ptr sets it to null before calling the destructor (because it's implemented in terms of reset(nullptr);. In libstdc++ however, unique_ptr's destructor just calls the destructor, its value remains valid during destruction.

Here's a testcase of the crash, extracted from the KIO code for which you can see the fix here. It works with gcc/libstdc++, and crashes with clang/libc++, because MyWindow::eventFilter() is using a d pointer that is null already. In this particular case the fix is easy, testing the event type before anything else. That's good practice anyway, for performance reasons. But there are other cases, where the situation was a bit different and the solution was to remove the event filter upon destruction.

I like unique_ptr, but beware of the interaction with event filters...

C++ on KDE Blogs

API documentation porting sprint

unique_ptr difference between libstdc++ and libc++ crashes your application