[alsa-devel] a newbie overwhelmed with this API

[Takashi Iwai]

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