API docs; functional or pretty?

[Thomas Zander]

Hi all.

I strongly believe in having good tools to make the job easier and get 
better results. For that reason I've been focussing on APIDocs recently 
since after the admin dir went RIP koffice didn't have any docs anymore.

I ended up with a script that solves several problems I've been having in 
KDEs docs.  I listed some important ones in my blog[1] but overall goal 
is to move from:
a) pretty docs that fit in the kde sites to ones functional for reference;
b) package based to class based searching.
Most devs don't know if a class comes from kdecore or kdeui or whatever, 
so they end up clicking and searching all. Moreover since the classes 
without docs don't show up anywhere it tends to be a hit and miss.
c) Better inter-project links.  I can now see (and click on) a parent 
class even if its in another lib.

And last, but not least,  a patch I wrote for doxygen to allow KDELibs to 
have all signals properly listed again since we tend to have Q_SIGNAL in 
the header files. see [2]

I'd like to get feedback from you guys to see if this can be used for 
broader consumption. Is the current state of online docs stopping you 
from using them as a good tool? You think the ones online for koffice 
better[3] ?
What can we do with the problem Adriaan put forth that as long as the docs 
don't look and behave like the kde - site (which IMO makes them unusable) 
we can't have them on developer.kde.org?

Thanks!


1) http://www.kdedevelopers.org/node/2102
2) http://members.home.nl/zander/signalsSlots.diff
3) http://www.koffice.org/developer/apidocs/
-- 
Thomas Zander
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20060622/7c1ade2a/attachment.sig>