[PD-dev] API documentation

[martin pichlmair]

> It's nice to have both. If you have a well documented API it's much 
> easier to decipher the source, since you can clearly see a description 
> of a function, its arguments, its return value, and what file it 
> resides in.
>
> If folks could provide me with information, I could spend some time 
> gluing it together into something nice looking.

i think the basic problem with api documentation is maintening it, not 
generating it. and i'm sure if you maintain the old external how-to a 
bit no one will bother you. it you start an api documentation then you 
should find a form that allows others to maintain it with you (wiki?) 
or you'll have to stick with it for years. api changes are rare but 
they happen (e.g. naming of externals in libs (keyword: nameclash) + 
help patches has changed or maybe will change. i know this is not 
directly a part of the api - it's part of the documentation though).

i'ld be glad if there would be a better starting point then the how-to.

and: nice working is better than nice looking :)

lg
martin