[LAU] Multichannel analog I/O audio interface: experiences and tips

[David Kastrup]

Fons Adriaensen <fons at linuxaudio.org> writes:

> On Tue, Jun 14, 2022 at 11:36:57PM +0200, Philippe Bekaert wrote:
>
>> Though I have 40 years of experience with c, and was a Linux user since 91,
>> I’m often scratching my head studying the alsa driver core. It’s really not
>> so easy …
>
> Not only driver code, the user space API docs have the same problem, and
> it's a common one with doxygen generated 'documentation'.
>
> Have a look at
> <https://www.alsa-project.org/alsa-doc/alsa-lib/group___p_c_m___s_w___params.html>
>
> 'Set period event inside a software configuration container.'
> 'Set silence size inside a software configuration container.'
> 'Set silence threshold inside a software configuration container.'
>
> etc. etc.
>
> None of these descriptions tell you anything you wouldn't know from 
> the actual function name. They are completely useless.
>
> But *nowhere* (AFAIK) it is explained what a 'period event' is, or
> why I should bother to set a 'silence threshold' or 'silence size'.
> You could as well try to learn a new language given only a dictionary.

You could call it a perversion of Donald Knuth's concept of "Literate
Programming" which presents a program as an essay, with the program code
embedded into the overarching documentation in a cohesive order.

You just leave off the overarching documentation and the program code
and the cohesive order.  It's sort of like serving a hard-boiled egg for
an order of soufflée.  Same thing except for a lack of structure.

-- 
David Kastrup