2.0 Goal: API Docs

[Max Howell]

Martin Aumueller wrote:
> On Thu September 14 2006 10:46, Jeff Mitchell wrote:
> [...]
>> 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.
> 
> I have to disagree a little: the prime goal should be to write code the 
> meaning of which is evident:
> - speaking variable and function names
> - consistent naming
> - don't leave out parameter names in prototypes in header files

This is very true.

I also thought I'd add that when I document a class I find it helps me 
think through all the aspects of the class and its functionality, 
purpose etc.

So it is a useful excercise to document stuff you expect to be general 
purpose. Classes that are helpers for other classes and have very 
specific use probably benefit less from documenting, but still it would 
be good, like Jeff says, to at least include an abstract to introduce 
what the class is meant to do.

But as you say, the most important thing is to use Qt-style 
function/class naming and make the names indicate clearly the function's 
purpose.

Also if a function needs 3 parameters, look at it and decide if you 
can't make it into separate functions eg:

for Qt3:
	new QProgressBar( "Deleting files", 0, 100, this, "frank" );

for Qt4 became:
	bar = new QProgressBar( this );
	bar->setLabelText( "deleting files" );
	bar->setRange( 0, 100 );
	bar->setObjectName( "frank" );

Max