Then the comments should be fixed up, of course. They can have embedded XML or HTML tags. They also can reference external documents.

I have no objection to long comments in header files. I do have objections to documentation that is not in sync with the code.

For an example of a well documented API done this way, see the Java class library documentation.

Regards,
Mike


-----Original Message-----
From: Istvan Varga 
Sent: Nov 15, 2005 11:15 AM
To: csound-devel@lists.sourceforge.net
Subject: Re: [Cs-dev] Csound 5 Reference Manual

Michael Gogins wrote:

> I would very much prefer more than one manual here. The API reference
 > (and the module reference) should be automatically generated from comments
 > in the code by doxygen or some similar tool. Otherwise, it will inevitably
 > get out of date.

Unfortunately, the documentation in the comments is often not quite
sufficient for anything other than a quick reference on the basic
syntax. For a real, detailed manual you need more than just comments
extracted from headers (that is, unless you do not mind having comments
of 1-2 pages or more for each function in the header files).
While a real manual might not be a strict requirement for a Csound 5
release, it would definitely be useful to have eventually, and make it
easier for people new to the Csound API to actually use it without
running into weird problems or having to look at the source code to
find important information that is not in the header comments.
Last, but not least, a full documentation is also a description of
standard behavior (also with explicit mentioning of what is undefined)
that one can rely on without strange compatibility issues in later
releases.

> That is why these tools are used in almost all open source  projects.

Many of those projects have quite poor documentation (e.g. ALSA).


-------------------------------------------------------
This SF.Net email is sponsored by the JBoss Inc.  Get Certified Today
Register for a JBoss Training Course.  Free Certification Exam
for All Training Attendees Through End of 2005. For more info visit:
http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/csound-devel





-------------------------------------------------------
This SF.Net email is sponsored by the JBoss Inc.  Get Certified Today
Register for a JBoss Training Course.  Free Certification Exam
for All Training Attendees Through End of 2005. For more info visit:
http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Steven Yi wrote:

> also find that most Java libraries publish API docs using Javadoc, but
> also put out manuals that are more illustrative of how to use the API.
>  So I see no problems with having both.

That is what I meant, having short but usable descriptions in
header files, and a separate more detailed manual. Obviously, the
latter should only be written when the API is reasonably stable
and finished, as it would otherwise easily get out of sync.

> would belong in the Users manual.  Otherwise, setting up a stubbed
> developer's manual shouldn't take too long to set up if someone would
> like me to do so.  Just a matter of where to put it(in csound5
> directory, create a new repository?).

I would prefer a new repository (or just a single manual with
both the user and development info, but that would probably be
too large, complex, and difficult to maintain), as the csound5
directory already has more than enough files.


-------------------------------------------------------
This SF.Net email is sponsored by the JBoss Inc.  Get Certified Today
Register for a JBoss Training Course.  Free Certification Exam
for All Training Attendees Through End of 2005. For more info visit:
http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net