2.0 Goal: API Docs

[Martin Aumueller]

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 something that can be kept up to date quite easily as the code 
evolves. However, API documentation that resides in comments will very soon 
disagree with the code. Or it is very hard to keep up to date. Thus, I 
suggest restricting this API doc efforts to the absolutely most central and 
important classes, such as MetaBundle.

Another important step for beginners (as well as senior Amarok developers) is 
making Amarok's components more independent from each other. A good example 
of many interdependencies are smart playlists. Cases like this should be 
minimized.