Lets document the API.

MIDIbox Documentation Project
1

Ok, Java programmers know what I’m talking about.  The online Java API *rocks*.  I will often write in Java simply because I know it is so well documented compared to other languages.  For those who don’t know, check this out: http://java.sun.com/j2se/1.3/docs/api/index.html

It’s the bomb. 

So, how about we begin working on a structure for documenting MIOS and all the MB applications in a similar manner?  Using the WIKI the results could be very good, and probably reduce the amount of redundant questions reguarding programming MB applications.

I’ve started with some basic ideas on how to format this, check out this page which lists all the files in the midibox SEQ zip file: http://www.midibox.org/dokuwiki/doku.php?id=midibox_seq_v2_4c

Scroll down and you can see that there is a link to a page for seq_gp.inc

http://www.midibox.org/dokuwiki/doku.php?id=seq_gp

which gives an overview of whats in that file along with a list of functions are variables that are used.  In time these lists should contain descriptions of what each function does and how each variable is being used in the file.  Links to detailed pages on each function where the code can be analyzed line by line should be included too. 

2

Hi moogah,

I’d surely love to get a more detailed API function list for MIOS, esp. useful for beginners; but I have to say that for my part I think it’s already perfect, because you don’t need too much information, else the danger is there to hide the relevant stuff.

About the MB app-docs:

Although I appreciate your efforts, I don’t understand it’s purpose: the code is very well commented, so if you don’t know what is what and what does something, just read the comments over the relevant function!

If the code is to be changed, you’ll stand before a huge pile of useless outdated docs with hundrets of files.

And normally sourcecode documentations are done via “docheader” directly in the code and then just exported as html.

It would be far more interesting to reveal some general ideas and concepts behind the code, because this is what you cannot read out so easily… the between-the-lines-concepts;

but one could always ask this in a forum thread…

so, I did hopefully not discourage you too much, it’s just my 2c :-\

best regards

Michael

3

And normally sourcecode documentations are done via “docheader” directly in the code 

As usual, TK is 3.5 years ahead of his time:

mios_doc.pl

# generates the MIOS documentation from the source files
# Thorsten Klose (2003-02-23)
#
# SYNTAX: mios_doc.pl <file(s)>

You can get it from the source code in the tools directory :slight_smile:

4

does this script only apply to MIOS?

I tried it on a .inc from the mb_fm package with no succes…

I agree with audiocommander about the concepts being more important

maybe a lot of C examples made by the MB community (with the help of Thorsten)

could fill this void?

5

It would be far more interesting to reveal some general ideas and concepts behind the code, because this is what you cannot read out so easily… the between-the-lines-concepts;

but one could always ask this in a forum thread…

This is what I mean, a sort of top-down approach to each application describing how each bit of functionality is accomplished, it makes sense to keep this documentation organized against the files and functions, no?  In particular I would have found it invaluable to have a list of the variables used in the MBSEQ application with a breif blurb about what they are, often it is hard to tell from just the name.

If the code is to be changed, you’ll stand before a huge pile of useless outdated docs with hundrets of files.

I know what you mean, but I don’t see this as a good reason not to try :).  Version numbers can be easily be posted with each page and old revisions can be moved to the back burner or just removed. 

I also like the idea of making “walkthroughs”.  ie: once I’m done with the modifications for the 808 sequencer I will post a journal of what I did in code, essentially a case study where I present several objectives and then document the process of completing them.   

6

In particular I would have found it invaluable to have a list of the variables used in the MBSEQ application with a breif blurb about what they are, often it is hard to tell from just the name.

normally the header in which the variable is declared contains a brief description of what this var is good for.

it makes sense to keep this documentation organized against the files and functions, no?

No, because you can really read very detailed comments in the sourcefiles.

The interesting parts are concepts that make it necessary to split the functionalities over different places are are not so easy to overlook, even if you read the description, because it is too detailed to get the whole view!

For example: if DIN occurs, check lookup-table, set variable state, poll timer, check variable state, do something, mark display to be refreshed, refresh display => in this easy example about 4 or 5 source files, and up to 7 functions are being called.

While you could describe the concept as: “press a button, store the state, check the state in a timer, refresh display when needed” (which would make it quite clear); your approach of additional documentation brings no light in this either, in contrary: it opens another battlefield of duplicated information, potential errors and misinterpretations. I also don’t think it’s an easy task to keep this up to date (esp. for MB-Seq 2.x where v3 is shortly before being released) :-\

Sorry for being so negative on good intentions, I really don’t want to discourage anyone, but I believe that adding your powers and time into releasing your own applications as examples to learn from (as mess said), or writing tutorials or walkthroughs (as you mentioned!) or any other descriptive stuff would be a lot more valueable (in my eyes :slight_smile: )

Or the extension of C-snippets found on the C-Page @ uCApps!

Keep it up, moogah!

Cheers,

ac