2.0 Goal: API Docs

[Jeff Mitchell]

(I'd add this to the Wiki, but until I get back from Hawai'i (FTW!)  
I'm not in a good position to do so, mainly because I don't want to be  
sending my password in cleartext over a publicly shared computer).

One thing I forgot to mention in my email 24 hours ago (and that I  
didn't see on the Wiki if it's already there) is that as we do the  
porting to QT/KDE 4, we are in the best position we'll ever be in for  
the next X years to add API documentation to every class, every  
function, and everywhere else it belongs.  I'll freely admit I'm as  
guilty as any of us (except for Max, and maybe one or two others) as  
far as not doing this, but we need it badly -- to help prevent  
confusion, wasted time trying to figure out what a function does, and  
so on.  Since we'll need to be reviewing pretty much every line of  
code in Amarok as we do the conversion, what better time to properly  
comment it?

I think a serious goal for 2.0 should be to have API documentation  
added everywhere that it belongs, such that we should be able to  
generate *complete* API documentation automatically.  It'll make  
things easier for us, easier for new people to help us code, and, dare  
I say it, help reverse the general view of Amarok coders among the KDE  
community as hacks.  We all know that we're the best media player out  
there; world-class programs deserve world-class documentation, and  
this is the time to do it.

--Jeff