On Jan 6, 2005, at 4:50 AM, martin pichlmair wrote:
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 :)
How about something like HeaderDoc? Its an open standard, reasonably common, and easy to implement. Plus the source for the API docs would be in the headers themselves, and therefore more likely to be maintained by those making changes to the API.
.hc
________________________________________________________________________ ____
Man has survived hitherto because he was too ignorant to know how to realize his wishes. Now that he can realize them, he must either change them, or perish. -William Carlos Williams