I don’t think doxygen or the like used in the kernel source is the main issue. It’s just that documentation isn’t written beyond evident rephrasings of function names and arguments as you say. It’s perfectly possible and practical to provide documentation of type 1 and 2 in the source files themselves, and maintain it there. And of course everyone touching the Linux audio sources has the necessary domain knowledge. Other issue is that much of the current documentation (eg alsa project site) seems to be terribly outdated. As said, I’m willing to contribute to documenting, if someone else (senior) takes a lead. I believe it could be a serious boost for Linux audio, especially pro. Best, ph Philippe Bekaert > Op 16 jun. 2022 om 15:56 heeft David Kastrup <dak@xxxxxxx> het volgende geschreven: > > Fons Adriaensen <fons@xxxxxxxxxxxxxx> writes: > >>> On Thu, Jun 16, 2022 at 02:24:13PM +0200, David Kastrup wrote: >>> >>> 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. >> >> I read his book ages ago (and still have a copy), but I don't agree >> with all of it. > > Well, it would be kind of unrealistic to expect a trailblazer to find > the best of all possible trajectories. I am perfectly willing to credit > a large contribution to the state of art without feeling the need to > call it perfect. > > It's just depressing that quite a few future implementations/concepts in > its wake are actually regressions in major respects. > > Knuth was willing to do what it takes to make his concept and tools work > for a particular program/implementation. Of course that makes a > difference and makes for a good proof of concept. > > How the like of doxygen are employed in the field is partly more a > counterproof of concept. Either way not all of the blame or praise > rests with the tool but rather the user's determination to actually make > it work for its purpose. > > -- > David Kastrup > _______________________________________________ > Linux-audio-user mailing list > Linux-audio-user@xxxxxxxxxxxxxxxxxxxx > https://lists.linuxaudio.org/listinfo/linux-audio-user _______________________________________________ Linux-audio-user mailing list Linux-audio-user@xxxxxxxxxxxxxxxxxxxx https://lists.linuxaudio.org/listinfo/linux-audio-user
