Despite the headline, this is a topic which may well be very boring to many people, but if you have no fear then read on (especially if you like elephants)...
You probably all remember how with the release of Qt4, Trolltech changed the way they recommended people to #include their classes. Previously one would include the header file describing QDir with #include <qdir.h> but with Qt4 it was changed such that one could do #include <QDir>. That is, if you wanted to include the header for a class you could simply put the classname between the pointy brackets (well actually I think it's recommended to put modulename/classname in there which means you have to look up which module the class is in, but let's ignore that for now). This makes it very easy to know how to include the stuff you need.
So, in the run-up to KDE4 there was much discussion about whether KDE should do the same. Some people were against it but it was decided that it doesn't hurt to allow these 'forwarding includes' since the normal includes are still there (the forwarding includes only #include the real headers themselves). Now, it was while working on a new highscore management system for kdegames (I'll probably blog about that later, you're not getting away that easily :D) that I noticed that in our apidox at http://api.kde.org we're still telling people to use the old include style. So, I looked at the doxygen manual and found that it has a feature to specify what the include file for any class should look like (you can see it here and there's also one for namespaces/structs and the like here). Armed with this knowledge I set about updating the kdelibs documentation to use it. It's a simple case of adding, for example:
\class KScoreManager kscoremanager.h <KScoreManager>
to the documentation block for the class. This makes the difference between this include and this one (see that #include line in the grey box near the top). The problem is, there's loads of classes to do this to and for each class (unfortunately there's sometimes more than one class in a header file) you've got to check whether there's a forwarding include for it (I guess internal classes don't need forwarding includes). In fact, if you download the tarball of the documentation for kdelibs from http://api.kde.org and make the following command from the root directory
find . -regex ".*\.html" -not \( -regex ".*source\.html" \) -not \( -regex ".*_8h\.html" \) -not \( -regex ".*_8cpp\.html" \) -exec grep -l --regexp=".*#include &lt;<.*\..*\..*</a>&gt;</code>.*" '{}' \; | wc -l
you'll find that there are about one and a half thousand classes this needs to be done to. That's a lot to do manually and given the nature of the changes to be made, difficult to do programatically. The good news is that if you call this command (which is sorta the opposite of the other one but without the wc -l)
find . -regex ".*\.html" -not \( -regex ".*source\.html" \) -not \( -regex ".*_8h\.html" \) -not \( -regex ".*_8cpp\.html" \) -exec grep -l --regexp=".*#include &lt;<.*\..*[^.].</a>&gt;</code>.*" '{}' \;
you'll see that there's already some classes doing it properly (Nepomuk, DNSSD and KFadeWidgetEffect).
Now, unless someone can think of a way of converting all the documentation automatically then all I can ask is that the next time you're doing some work on a library class, firstly make sure you're installing forwarding headers (preferably 1 per class even if both forwarding headers forward to the same real header) and secondly just add the \class ... line to the class documentation block and make the world a more attractive looking place.
P.S. I'd like to dedicate this post to Jesper K. Pedersen, the author of KRegExpEditor without which this post would not have been possible.
P.P.S. Okay, so I lied about the elephants but if you do a search and replace with "class"→"elephant" this post is a lot more exciting.
