|
»
API documentation
|
View:
New views
20 Messages
—
Rating Filter:
Alert me
|
| < Prev | 1 - 2 | Next > |
 |
API documentation
by Victor Lazzarini
::
Rate this Message:
Some parts of this message have been removed.
Learn more about Nabble's security policy.
I propose we have a good C API reference for
the next release. I can initiate it,
but I hope we can collaborate on this.
We could use the same format that has been used for
the manual. So if Andres
could put a section in it called API reference and
a template XML file, then we can
proceed from the top of csound.h down.
Victor
------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by RoryWalsh
::
Rate this Message:
I created a html version of csound.h using doxygen which formatted
things quite well and looks pretty good. Should we then simply start editing csound.h rather than starting with a whole new format such as is in the reference manual, just a thought. Either way I'd be happy to contribute examples and such. Rory. 2009/10/21 victor <Victor.Lazzarini@...>: > I propose we have a good C API reference for the next release. I can > initiate it, > but I hope we can collaborate on this. > > We could use the same format that has been used for the manual. So if Andres > could put a section in it called API reference and a template XML file, then > we can > proceed from the top of csound.h down. > > Victor > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Victor Lazzarini
::
Rate this Message:
No. I think we need to do a proper reference manual. Doxygen is only good
as a stop-gap measure. Victor ----- Original Message ----- From: "Rory Walsh" <rorywalsh@...> To: "Developer discussions" <csound-devel@...> Sent: Wednesday, October 21, 2009 9:29 AM Subject: Re: [Cs-dev] API documentation I created a html version of csound.h using doxygen which formatted things quite well and looks pretty good. Should we then simply start editing csound.h rather than starting with a whole new format such as is in the reference manual, just a thought. Either way I'd be happy to contribute examples and such. Rory. 2009/10/21 victor <Victor.Lazzarini@...>: > I propose we have a good C API reference for the next release. I can > initiate it, > but I hope we can collaborate on this. > > We could use the same format that has been used for the manual. So if > Andres > could put a section in it called API reference and a template XML file, > then > we can > proceed from the top of csound.h down. > > Victor > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Michael Gogins-2
::
Rate this Message:
Doxygen is the best way to do a reference manual. I used to work as a technical writer before I started working as a programmer. The manuals that I and my colleagues made with doxygen and similar tools were both more complete and more useful than the ones we did by hand. Doxygen also has the advantage of being a drop dead simple toolchain. Please expand on the existing manual and do not reinvent wheels. Mkg On Oct 21, 2009 4:33 AM, "victor" <Victor.Lazzarini@...> wrote: ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Stéphane Rollandin
::
Rate this Message:
> I propose we have a good C API reference for the next release.
... > We could use the same format that has been used for the manual. +1 Stef ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by jpff-2
::
Rate this Message:
Like Victor I am suspicious of doxygen "manuals". I have not seen one
yet that told be anything useful. ==John ffitch ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Jacob Joaquin
::
Rate this Message:
I'm also of the mind that doxygen is most likely not a sufficient
solution. We need a manual that caters to composers, not technical C/C++ gurus. I'm spreading myself thin these days, but I'll be happy to help out in any way I can. This API manual is too important to not do it right. Best, Jake On Wed, Oct 21, 2009 at 5:57 AM, jpff <jpff@...> wrote: > Like Victor I am suspicious of doxygen "manuals". I have not seen one > yet that told be anything useful. > ==John ffitch > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Michael Gogins-2
::
Rate this Message:
I have verified that the following projects use Doxygen or similar
tools that transform comments in source code to generate reference manuals. These include some of the important tools and third party packages used by Csound. Java API reference FLTK class reference wxWidgets class reference PortAudio reference PortMidi reference The GNU libstd++ reference (i.e. the Standard C++ Library that we use to build the C++ parts of Csound) I submit that most Csound developers would have learned something useful from the above sources. Unless you guys know all this stuff by heart. Regards, Mike On 10/21/09, jpff <jpff@...> wrote: > Like Victor I am suspicious of doxygen "manuals". I have not seen one > yet that told be anything useful. > ==John ffitch > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > -- Michael Gogins Irreducible Productions http://www.michael-gogins.com Michael dot Gogins at gmail dot com ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Jacob Joaquin
::
Rate this Message:
> We need a manual that caters to composers, not technical
> C/C++ gurus. To be clear, the manual should also be a good tech manual, in addition to catering to composers. Best, Jake --- The Csound Blog - http://csound.noisepages.com/ ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by RoryWalsh
::
Rate this Message:
I've uploaded the simple examples I created from the csound api using
doxygen, I think they look good and with a few more comments could be very good. Granted it's far from perfect but keeping all the comments/examples and what not in the source seems like a good idea to me. You can check them out here: http://rorywalsh.ear.ie/csoundDoxy/html/index.html As csound.h is currently the only file comments you will need to hit the Files tab and click on csound.h, half way down the page there is a list of the different functions. These could easily be altered to include sample code. Rory. 2009/10/21 Michael Gogins <michael.gogins@...>: > I have verified that the following projects use Doxygen or similar > tools that transform comments in source code to generate reference > manuals. These include some of the important tools and third party > packages used by Csound. > > Java API reference > FLTK class reference > wxWidgets class reference > PortAudio reference > PortMidi reference > The GNU libstd++ reference (i.e. the Standard C++ Library that we use > to build the C++ parts of Csound) > > I submit that most Csound developers would have learned something > useful from the above sources. Unless you guys know all this stuff by > heart. > > Regards, > Mike > > > > > > > > > On 10/21/09, jpff <jpff@...> wrote: >> Like Victor I am suspicious of doxygen "manuals". I have not seen one >> yet that told be anything useful. >> ==John ffitch >> >> ------------------------------------------------------------------------------ >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA >> is the only developer event you need to attend this year. Jumpstart your >> developing skills, take BlackBerry mobile applications to market and stay >> ahead of the curve. Join us from November 9 - 12, 2009. Register now! >> http://p.sf.net/sfu/devconference >> _______________________________________________ >> Csound-devel mailing list >> Csound-devel@... >> https://lists.sourceforge.net/lists/listinfo/csound-devel >> > > > -- > Michael Gogins > Irreducible Productions > http://www.michael-gogins.com > Michael dot Gogins at gmail dot com > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Stéphane Rollandin
::
Rate this Message:
yes, doxygen stuff does not explain how to use the API. while it is very
much worthwhile, IMO it is definitely in need of some human-written documentation giving an overall picture of the whole API structure and usage. Stef ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by RoryWalsh
::
Rate this Message:
Yes I agree but doxygen manuals can include all this info. Check out
the manuals for the projects Michael listed above, especially the wxWidgets which I use extensively. http://docs.wxwidgets.org/2.6/wx_classref.html Each of the class refs include examples where needed. There is also an overview page too, all this can be done with doxygen. I've played around with the current reference manual and it's a nightmare to edit. Rory. 2009/10/21 Stéphane Rollandin <lecteur@...>: > yes, doxygen stuff does not explain how to use the API. while it is very > much worthwhile, IMO it is definitely in need of some human-written > documentation giving an overall picture of the whole API structure and > usage. > > Stef > > > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Steven Yi
::
Rate this Message:
Agreed. It's the same issue with Javadocs. One thing I liked about
Rory's example he just posted is the main page has quite a bit of info. I don't see it as either-or but really we need both, documentation on the level of API library as well as higher-level integration documentation to explain how to use the pieces together. Whether we create a Doxygen doc and separate doc for big-picture or try to do as Rory shows by integrating the big-picture doc isn't a big issue for me as long as both are represented. As for designing the API docs for composers, I don't know what that means really. When I'm composing I don't want to think about API's. :P If it means making the API easy to use and well documented, then I'm all for it. steven 2009/10/21 Stéphane Rollandin <lecteur@...>: > yes, doxygen stuff does not explain how to use the API. while it is very > much worthwhile, IMO it is definitely in need of some human-written > documentation giving an overall picture of the whole API structure and > usage. > > Stef > > > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Felipe Sateler
::
Rate this Message:
I believe that an accurate reference manual is a prerequisite for any
other sort of documentation on the API. And doxygen is just the right tool for creating reference manuals. A separate manual can be in the form of a how-to, tutorial or getting started guide. The doxygen information is good. However, it is hard to find what is useful and what is not. Lots of undocumented structures, #defines and other stuff. Most of them because (AFAIK) they don't need to be used by an API user. In that case, they should be hidden from the documentation. I'm not quite sure how to do this. It is really ironic that a package designed to create documentation has it in a very difficult to search/browse form. On Wed, 2009-10-21 at 06:29 -0700, Jacob Joaquin wrote: > I'm also of the mind that doxygen is most likely not a sufficient > solution. We need a manual that caters to composers, not technical > C/C++ gurus. > > I'm spreading myself thin these days, but I'll be happy to help out in > any way I can. This API manual is too important to not do it right. > > Best, > Jake > > > On Wed, Oct 21, 2009 at 5:57 AM, jpff <jpff@...> wrote: > > Like Victor I am suspicious of doxygen "manuals". I have not seen one > > yet that told be anything useful. > > ==John ffitch > > > > ------------------------------------------------------------------------------ > > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > > is the only developer event you need to attend this year. Jumpstart your > > developing skills, take BlackBerry mobile applications to market and stay > > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > > http://p.sf.net/sfu/devconference > > _______________________________________________ > > Csound-devel mailing list > > Csound-devel@... > > https://lists.sourceforge.net/lists/listinfo/csound-devel > > > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel -- Saludos, Felipe Sateler ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Victor Lazzarini
::
Rate this Message:
While I have not used all of the packages below, I have used some of them,
and my opinion of their documentation standard is not very high. Victor ----- Original Message ----- From: "Michael Gogins" <michael.gogins@...> To: "Developer discussions" <csound-devel@...> Sent: Wednesday, October 21, 2009 2:34 PM Subject: Re: [Cs-dev] API documentation >I have verified that the following projects use Doxygen or similar > tools that transform comments in source code to generate reference > manuals. These include some of the important tools and third party > packages used by Csound. > > Java API reference > FLTK class reference > wxWidgets class reference > PortAudio reference > PortMidi reference > The GNU libstd++ reference (i.e. the Standard C++ Library that we use > to build the C++ parts of Csound) > > I submit that most Csound developers would have learned something > useful from the above sources. Unless you guys know all this stuff by > heart. > > Regards, > Mike > > > > > > > > > On 10/21/09, jpff <jpff@...> wrote: >> Like Victor I am suspicious of doxygen "manuals". I have not seen one >> yet that told be anything useful. >> ==John ffitch >> >> ------------------------------------------------------------------------------ >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA >> is the only developer event you need to attend this year. Jumpstart your >> developing skills, take BlackBerry mobile applications to market and stay >> ahead of the curve. Join us from November 9 - 12, 2009. Register now! >> http://p.sf.net/sfu/devconference >> _______________________________________________ >> Csound-devel mailing list >> Csound-devel@... >> https://lists.sourceforge.net/lists/listinfo/csound-devel >> > > > -- > Michael Gogins > Irreducible Productions > http://www.michael-gogins.com > Michael dot Gogins at gmail dot com > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Michael Gogins-2
::
Rate this Message:
I thought we were discussing a reference manual.
Typically, for a piece of sofware, there is a reference manual that documents all of the functions and facilities of the software without reference to how they might be used. This is what Doxygen or javadoc is the best tool for. And there is also a user guide that documents how to use the software, starting with basic use cases and going on from there. For example, in the Java documentation, the "API Documentation" is a reference manual generated by javadoc, and the various separate "Tutorials" are the user guides. Similarly, for wxWidgets, there is one manual, in the form of a user's guide, but it contains a class reference section that is completely generated by Doxygen. If you need a Csound API manual for composers, you do not need a technical reference only (though you still do need that). You also need a user guide. Doxygen and its ilk are, of course, not the right tool for writing user guides. "A Csound Tutorial" and the CsoundAC tutorial, both by me, both have material that is more like a user guide, but they do not go into enough detail. I do not know how much detail is really required. Possibly "A Csound Tutorial" could be expanded with material on programming new client for the Csound API that uses the Csound performance thread, and control channels. This would be 5-10 pages of additional material, and cover most of what most programmers would need to know. But it might be a better, because less confusing, to do an all-new Csound API User's Guide that is just about using the API. This would not replace the existing API reference, it would supplement it. User guides are more work than reference manuals. I think you guys are completely correct that we need a better user guide to the API, but you are wrong that there is a need to replace the reference. They are not the same kind of animal. Regards, Mike On 10/21/09, Jacob Joaquin <jacobjoaquin@...> wrote: > I'm also of the mind that doxygen is most likely not a sufficient > solution. We need a manual that caters to composers, not technical > C/C++ gurus. > > I'm spreading myself thin these days, but I'll be happy to help out in > any way I can. This API manual is too important to not do it right. > > Best, > Jake > > > On Wed, Oct 21, 2009 at 5:57 AM, jpff <jpff@...> wrote: >> Like Victor I am suspicious of doxygen "manuals". I have not seen one >> yet that told be anything useful. >> ==John ffitch >> >> ------------------------------------------------------------------------------ >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA >> is the only developer event you need to attend this year. Jumpstart your >> developing skills, take BlackBerry mobile applications to market and stay >> ahead of the curve. Join us from November 9 - 12, 2009. Register now! >> http://p.sf.net/sfu/devconference >> _______________________________________________ >> Csound-devel mailing list >> Csound-devel@... >> https://lists.sourceforge.net/lists/listinfo/csound-devel >> > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > -- Michael Gogins Irreducible Productions http://www.michael-gogins.com Michael dot Gogins at gmail dot com ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Jacob Joaquin
::
Rate this Message:
What I meant when I said write the API for composers is that we need
to write docs for our target audience. That's everyone from people who just want to algorithmically generate some sine waves to full on developers using Csound as a synth engine in their software. As you put it, making the API docs easy and well documented. I may have jumped the gun with my disapproval of doxygen. I really don't care what is used as long as the manual itself is well written and well organized. I'm just happy that there seems to be much enthusiasm for this much needed manual. We should still take the time to study the alternatives, and try to find the right platform for the job at hand. In the mean time, maybe can try to define what the goals for the API manual are? Best, Jake --- The Csound Blog - http://csound.noisepages.com/ On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi <stevenyi@...> wrote: > Agreed. It's the same issue with Javadocs. One thing I liked about > Rory's example he just posted is the main page has quite a bit of > info. I don't see it as either-or but really we need both, > documentation on the level of API library as well as higher-level > integration documentation to explain how to use the pieces together. > Whether we create a Doxygen doc and separate doc for big-picture or > try to do as Rory shows by integrating the big-picture doc isn't a big > issue for me as long as both are represented. > > As for designing the API docs for composers, I don't know what that > means really. When I'm composing I don't want to think about API's. :P > If it means making the API easy to use and well documented, then I'm > all for it. > > steven ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Michael Gogins-2
::
Rate this Message:
I think the documentation standard for Java is very high, and I think
most technical writers and programmers would agree. There are tutorials for all typical use cases of a very large system, they go into adequate technical detail, there are overviews of the entire Java system and of each subsystem, and I find the javadoc API reference to be complete and almost entirely error-free. I have had to do less stumbling around and experimenting after reading the Java documentation than with any other system, with the single exception of the Sybase documentation, which sets the standard in my opinion. Python is quite well documented, but it is harder to navigate the Python documentation than the Java documentation. Regards, Mike On 10/21/09, victor <Victor.Lazzarini@...> wrote: > While I have not used all of the packages below, I have used some of them, > and my opinion of their documentation standard is not very high. > > Victor > > ----- Original Message ----- > From: "Michael Gogins" <michael.gogins@...> > To: "Developer discussions" <csound-devel@...> > Sent: Wednesday, October 21, 2009 2:34 PM > Subject: Re: [Cs-dev] API documentation > > >>I have verified that the following projects use Doxygen or similar >> tools that transform comments in source code to generate reference >> manuals. These include some of the important tools and third party >> packages used by Csound. >> >> Java API reference >> FLTK class reference >> wxWidgets class reference >> PortAudio reference >> PortMidi reference >> The GNU libstd++ reference (i.e. the Standard C++ Library that we use >> to build the C++ parts of Csound) >> >> I submit that most Csound developers would have learned something >> useful from the above sources. Unless you guys know all this stuff by >> heart. >> >> Regards, >> Mike >> >> >> >> >> >> >> >> >> On 10/21/09, jpff <jpff@...> wrote: >>> Like Victor I am suspicious of doxygen "manuals". I have not seen one >>> yet that told be anything useful. >>> ==John ffitch >>> >>> ------------------------------------------------------------------------------ >>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA >>> is the only developer event you need to attend this year. Jumpstart your >>> developing skills, take BlackBerry mobile applications to market and stay >>> ahead of the curve. Join us from November 9 - 12, 2009. Register now! >>> http://p.sf.net/sfu/devconference >>> _______________________________________________ >>> Csound-devel mailing list >>> Csound-devel@... >>> https://lists.sourceforge.net/lists/listinfo/csound-devel >>> >> >> >> -- >> Michael Gogins >> Irreducible Productions >> http://www.michael-gogins.com >> Michael dot Gogins at gmail dot com >> >> ------------------------------------------------------------------------------ >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA >> is the only developer event you need to attend this year. Jumpstart your >> developing skills, take BlackBerry mobile applications to market and stay >> ahead of the curve. Join us from November 9 - 12, 2009. Register now! >> http://p.sf.net/sfu/devconference >> _______________________________________________ >> Csound-devel mailing list >> Csound-devel@... >> https://lists.sourceforge.net/lists/listinfo/csound-devel > > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > -- Michael Gogins Irreducible Productions http://www.michael-gogins.com Michael dot Gogins at gmail dot com ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Michael Gogins-2
::
Rate this Message:
As I said previously, we need two manuals, not one. We need the
current API reference manual generated from Doxygen, which and and should be be improved by improving the comments in the source code. We also need a separate "Csound API User's Guide" to cover material such as: -- What the basic purposes and uses of the API are and could be. -- What the various layers in the API are and what they are for (this exists in the reference, but should moved into the user's guide and expanded). -- Linking with the Csound API libraries in various platforms, languages, toolchains: at a minimum C, C++, Python, and Java on Windows/MinGW, Linux, and OS X. -- Using the basic Csound API to just render a csd. -- Using the performance-thread stuff to embed Csound in programs that also do other things while Csound runs. -- Using the event channel stuff with client GUIs. -- Using the Csound file management stuff. -- Feeding audio into, and out of, Csound as it runs; this currently works with C, C++, and Java at least but few people do it because it is very hard to just figure out. Regards, Mike On 10/21/09, Jacob Joaquin <jacobjoaquin@...> wrote: > What I meant when I said write the API for composers is that we need > to write docs for our target audience. That's everyone from people > who just want to algorithmically generate some sine waves to full on > developers using Csound as a synth engine in their software. As you > put it, making the API docs easy and well documented. > > I may have jumped the gun with my disapproval of doxygen. I really > don't care what is used as long as the manual itself is well written > and well organized. I'm just happy that there seems to be much > enthusiasm for this much needed manual. We should still take the time > to study the alternatives, and try to find the right platform for the > job at hand. > > In the mean time, maybe can try to define what the goals for the API manual > are? > > Best, > Jake > --- > The Csound Blog - http://csound.noisepages.com/ > > > > On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi <stevenyi@...> wrote: >> Agreed. It's the same issue with Javadocs. One thing I liked about >> Rory's example he just posted is the main page has quite a bit of >> info. I don't see it as either-or but really we need both, >> documentation on the level of API library as well as higher-level >> integration documentation to explain how to use the pieces together. >> Whether we create a Doxygen doc and separate doc for big-picture or >> try to do as Rory shows by integrating the big-picture doc isn't a big >> issue for me as long as both are represented. >> >> As for designing the API docs for composers, I don't know what that >> means really. When I'm composing I don't want to think about API's. :P >> If it means making the API easy to use and well documented, then I'm >> all for it. >> >> steven > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > -- Michael Gogins Irreducible Productions http://www.michael-gogins.com Michael dot Gogins at gmail dot com ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
|
|
Re: API documentation
by Jacob Joaquin
::
Rate this Message:
I think this is a great start. Two manuals sounds like a very
plausible solution. And if later it makes sense to combine them into a single doc, the Csound API User's Guide could be one section, while the reference manual could be another section. If we work under the philosophy of "release early, release often" then perhaps we could start prioritizing what needs to be done first, so that we can get some information up ASAP. This way, more people can start getting their hands on the API sooner, while at the same time, help communicate to the outside world that Csound is still very much an active project. As soon as I get some time, I'll look into writing some examples. And I'll be happy to proof read anything and everything. Best, Jake --- The Csound Blog - http://csound.noisepages.com/ On Wed, Oct 21, 2009 at 8:44 AM, Michael Gogins <michael.gogins@...> wrote: > As I said previously, we need two manuals, not one. We need the > current API reference manual generated from Doxygen, which and and > should be be improved by improving the comments in the source code. > > We also need a separate "Csound API User's Guide" to cover material such as: > > -- What the basic purposes and uses of the API are and could be. > -- What the various layers in the API are and what they are for (this > exists in the reference, but should moved into the user's guide and > expanded). > -- Linking with the Csound API libraries in various platforms, > languages, toolchains: at a minimum C, C++, Python, and Java on > Windows/MinGW, Linux, and OS X. > -- Using the basic Csound API to just render a csd. > -- Using the performance-thread stuff to embed Csound in programs that > also do other things while Csound runs. > -- Using the event channel stuff with client GUIs. > -- Using the Csound file management stuff. > -- Feeding audio into, and out of, Csound as it runs; this currently > works with C, C++, and Java at least but few people do it because it > is very hard to just figure out. > > Regards, > Mike > > On 10/21/09, Jacob Joaquin <jacobjoaquin@...> wrote: >> What I meant when I said write the API for composers is that we need >> to write docs for our target audience. That's everyone from people >> who just want to algorithmically generate some sine waves to full on >> developers using Csound as a synth engine in their software. As you >> put it, making the API docs easy and well documented. >> >> I may have jumped the gun with my disapproval of doxygen. I really >> don't care what is used as long as the manual itself is well written >> and well organized. I'm just happy that there seems to be much >> enthusiasm for this much needed manual. We should still take the time >> to study the alternatives, and try to find the right platform for the >> job at hand. >> >> In the mean time, maybe can try to define what the goals for the API manual >> are? >> >> Best, >> Jake >> --- >> The Csound Blog - http://csound.noisepages.com/ >> >> >> >> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi <stevenyi@...> wrote: >>> Agreed. It's the same issue with Javadocs. One thing I liked about >>> Rory's example he just posted is the main page has quite a bit of >>> info. I don't see it as either-or but really we need both, >>> documentation on the level of API library as well as higher-level >>> integration documentation to explain how to use the pieces together. >>> Whether we create a Doxygen doc and separate doc for big-picture or >>> try to do as Rory shows by integrating the big-picture doc isn't a big >>> issue for me as long as both are represented. >>> >>> As for designing the API docs for composers, I don't know what that >>> means really. When I'm composing I don't want to think about API's. :P >>> If it means making the API easy to use and well documented, then I'm >>> all for it. >>> >>> steven >> >> ------------------------------------------------------------------------------ >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA >> is the only developer event you need to attend this year. Jumpstart your >> developing skills, take BlackBerry mobile applications to market and stay >> ahead of the curve. Join us from November 9 - 12, 2009. Register now! >> http://p.sf.net/sfu/devconference >> _______________________________________________ >> Csound-devel mailing list >> Csound-devel@... >> https://lists.sourceforge.net/lists/listinfo/csound-devel >> > > > -- > Michael Gogins > Irreducible Productions > http://www.michael-gogins.com > Michael dot Gogins at gmail dot com > > ------------------------------------------------------------------------------ > Come build with us! The BlackBerry(R) Developer Conference in SF, CA > is the only developer event you need to attend this year. Jumpstart your > developing skills, take BlackBerry mobile applications to market and stay > ahead of the curve. Join us from November 9 - 12, 2009. Register now! > http://p.sf.net/sfu/devconference > _______________________________________________ > Csound-devel mailing list > Csound-devel@... > https://lists.sourceforge.net/lists/listinfo/csound-devel > ------------------------------------------------------------------------------ Come build with us! The BlackBerry(R) Developer Conference in SF, CA is the only developer event you need to attend this year. Jumpstart your developing skills, take BlackBerry mobile applications to market and stay ahead of the curve. Join us from November 9 - 12, 2009. Register now! http://p.sf.net/sfu/devconference _______________________________________________ Csound-devel mailing list Csound-devel@... https://lists.sourceforge.net/lists/listinfo/csound-devel |
signature.asc (853 bytes) | < Prev | 1 - 2 | Next > |
| Free embeddable forum powered by Nabble | Forum Help |
