At Sat, 04 Aug 2007 21:50:24 +1000, Adam Seychell wrote:

I'm writing simple audio application and I have successfully used the DirectSound API under Windows. Now I'm looking at porting to Linux using ALSA. I have tried reading the online ALSA API documentation, but it seems too early in development and insufficient compared what one can learn reading Microsoft's DirectX SDK documentation. Excuse my ignorance for a minute, but the API seems quite large compared to DirectSound and so I'm wondering if there is good reason why so many functions exists ? Was there an early design decision not to write ALSA in C++ ?

I would like to help out with documentation but of course I thats impossible for someone who is a complete novice to the ALSA project. I know that writing good documentation takes a lot of hard work, especially for software developers who spend enough time on coding. Its an unfortunate paradox among all open source projects. Software developers who posses the knowledge can't readily communicate it to potential volunteer documentation writers in an open source environment.

Yeah, the documentation has always been a problem.

What I'd like to propose is:

- concentrate only on basic functions, gather up these functions in a page for "basic operations", instead of spreading all over.

- drop the rare used functions, from documentation and mark it deprecated eventually. 90% of existing functions could be in this category.

Then API references would be much smaller and readable, at least. The additional more verbose description can be added later on.

Takashi