16 Jun
2022
16 Jun
'22
5:39 p.m.
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. There are two very different things that need docs:
1. The algorithm used, or the intended workings of the system that
is controlled by an API,
2. The actual implementation.
(2) can be mixed with the code - it is what you need for maintaining
the code, fix bugs, etc.
(1) has aspects that could be mixed with the code in simple cases,
but in general this should be some form of design document. It should
make clear what the code is supposed to do and how, or what exactly
the API is supposed to control and how. And at least it should define
all the terminology used in (1) and in the code itself.
For any API there will be an underlying 'model' of what is actually
controlled by that API. This is the missing part for the ALSA libs.
There is also (0) - domain specific knowledge. You may expect a
user to have this - there should be no need to explain what 'PCM'
means in the ALSA docs.
But expect a disaster if code is written by an author who doesn't
have the necessary background, just from some formal specification,
unless those specs are written and the code is reviewed by someone
with domain-specific knowledge. But that is a different problem.
Ciao,
--
FA