16 Jun
2022
16 Jun
'22
10:50 p.m.
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(a)gnu.org> het volgende geschreven:
Fons Adriaensen <fons(a)linuxaudio.org> writes:
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(a)lists.linuxaudio.org
https://lists.linuxaudio.org/listinfo/linux-audio-user
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.