I recently saw a good saying;
All KDE hackers I know are pretty bright and the above will sound true to them; having well working tools gets you better results, faster.
KDE continues to have less then optimal API docs, though, and I think thats because they are not seen as a tool to enhance your workflow with. Many people still read the header files as a way to figure out which methods there are to call. Optimizing the tools to find the header files instead of optimizing the online api docs. Makes sense, in a way.
I like my workflow of having a couple of tabs with api docs open; one for each major library. So I set out to optimize the html version of the tools of the trade. There is a couple of things I really miss in the docs that KDE produces right now (which are available on developer.kde.org).
I set out to fix those issues because koffice was without any docs since the Makefile.ams were removed from svn and kde's doc guru didn't seem to have time to fix it. Itch to scratch and all that :)
When talking to the kde docs guru my comments were shrugged off; he basically told me if it does not fit in the kde layout he doesn't care about my efforts. Fair enough. But I did put the script in koffice svn and its generic enough to be used in all modules that want it without any modifications. So I hope that there are other KDE developers willing to give it a try and benefit from the increased usefullness of the docs we type.
It also appears that the docs-script for developer.kde.org are rather anal about forcing developers to learn proper doxygen tags. Like we don't have enough to learn already. This apparently it not needed at all and doxygen can provide a class description without the developer having to type \brief in front of it, among other clear wins.
So, I hope I made a compelling sales pitch here; better output with less effort. Don't you want that ? :)
or watch its output here: