| I'm quite willing to supply the documentation you would like to see.
What I propose is a general introduction to the purpose of the API,
high-level architecture, and TO DOs together with some sample uses of the
API, to be attached as an introduction to the Doxygen-generated HTML, and
to be checked into CVS. The Doxygen step should then be added to the build.
Anyone who builds Csound from sources will have all the API documentation,
and I think the build system can be tweaked so that the documentation is
also included in the archive.
I do not think that detailed documentation of each function, beyond what is
contained in the header, is either necessary or desirable; if that
documentation is not adequate, the comments should be elaborated to make
the Doxygen stuff more usable. My reasoning arises from the experience that
documenting the same thing in two places leads to contradictions.
Please let me know if you would prefer a different approach.
Original Message:
-----------------
From: Richard Dobson richarddobson@blueyonder.co.uk
Date: Tue, 18 Nov 2003 16:10:49 +0000
To: csound-dev@eartha.mills.edu
Subject: [CSOUND-DEV:3384] Re: Road to Reentrancy
I think what we need now, especially now that Csound is on CVS, is
formal documentation of csound.h and the API in general (even if still
subject to change), so that not only those privy to an archive of this
list, but those who may discover Csound CVS tomorrow, have
self-contained information. Annotating each function is not enough - we
need a synopsis of the architecture, design philosopy and a "TODO" list
too. I have done a quick search for "csound.h" in my stock of posts, and
find plenty of snippets about this and that (discussions more than
documentation), so I am in much the same situation as John, and I think
other people may be too. It would be impossible for me to assemble
complete and accurate formal documentation on this just from the bits
and bobs in various posts to the list, any more than I could reconstruct
the VST SDK from posts to the vst dev list.
This documentation would then itself go into CVS so that it is
automatically there with all the other files.
Someone will write a book about all this one day...
:-)
Richard Dobson
Michael Gogins wrote:
> I have made repeated explanations of the function of this file to the list
> and to John. Never has John asked for a clarification of my explanation if
> he did not understand it.
>
--------------------------------------------------------------------
mail2web - Check your email from the web at
http://mail2web.com/ . |