[PD-dev] API documentation

[Hans-Christoph Steiner]

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