Fons Adriaensen <fons@xxxxxxxxxxxxxx> 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 _______________________________________________ Linux-audio-user mailing list Linux-audio-user@xxxxxxxxxxxxxxxxxxxx https://lists.linuxaudio.org/listinfo/linux-audio-user
