KDE Frameworks Documentation

[Ignat Semenov]

Hello KDE devs and users!

You may remember me as that guy on IRC that's constantly building
something, always finds bugs in the buildsystem and never gives back
code. Well, for a reason, it turns out. :)

There was a recent blog post by Sebastian Trug (please forgive the
umlaut, got no idea how to type it) about fixing Nepomuk bugs, mostly
crashes. So I commented on that blog describing my experience
regarding attempts at KDE apps bugfixing. After leaving the comment, I
realised this might be a good idea, so I'm posting it here.

Once upon a time, I wanted to fix a bug in Dolphin regarding previews.
Well, simple, isn't it? Turned out to be the most difficult
programming and reverse engineering task I've ever seen. So here are
my thoughts on what did not allow me to fix the bug (quoting the
comment on Sebastian's blog):

"I have to say that the whole multi-process architecture of KDE,
multiplied by the usage of tons of wrappers, all of them with their
own API, and by the un-debuggable nature of Qt signals-and-slots /
meta-object system makes KDE app debugging and bug fixing a royal
pain. I once tried to trace down a Dolphin bug regarding previews. I
found like 5 tiers of abstraction, lots of processes, insanely complex
APIs and swore not to try to fix KDE bugs any more, at least in
Dolphin or the KIO subsystem."

This means:

1)It was all split into many processes, and thus impossible to debug
without black magic.
2)The API was similar to an onion, I think I did not remove all the
layers, even after spending some time.
3)Qt meta-information, esp. signals and slots, gets in the way.
4)(Similar to #1) KIO or whatever it was turned out to be
asynchronous, multi-process beast, and next to impossible to debug.
YOu have to attach to multiple processes and watch them all, but to do
that, you need to know where to attach and what to watch for.

Thus, here's my proposal (one mroe blog post comment quote):

"KDE Core Libs and Frameworks *do* need good up-to-date documentation,
which would cover such aspects of the named Libs and Frameworks as the
API (with comments and probably examples), the process structure with
MSDs (arguably the most important part, the graphics!), the design
rationale for certan complex pieces of Frameworks. This would lower
the barrier for bug-fixing as currently only the main application /
library dev knows why the heck his app is as complex as a space
shuttle when all it does is simply list files that are on the hard
disk."

This means:

1)API docs up-to-date and with extensive examples.
2)MSDs!!!! And component interaction diagrams. Especialy for anything
that is asyncronous and multi-process like KIO is.
3)Why it was done this or that way. For complex pieces of library or
framework subsystems it might be very helpful.
4)Same for APPS would be ideal, but it's probably not realistic.

If you do this, you will see bugs go away in real-time. While it's not
done, well, you can call in as many contributors as you want, but when
they encounter what I've described above, they might reconsider their
decision, and for a good reason.

I sincerely hope Aaron is in a good mood today ;) and will not reject
my proposal immediately or consider it as a rant. Aaron and other KDE
code devs aka gods, please, treat this proposal constructively. I
might even go as far as creating a blog and posting this to raise
public awareness of the issue.

Best regards,
Ignat Semenov aka thorGT