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