On 20.10.25 23:02, Chuck Wolber wrote:
[Reposting with apologies for the dup and those inflicted by the broken Gmail
defaults. I have migrated away from Gmail, but some threads are still stuck
there.]
On Mon, Oct 20, 2025 at 7:35 PM David Hildenbrand <[email protected]> wrote:
+------------
+The Documentation/doc-guide/kernel-doc.rst chapter describes how to document
the code using the kernel-doc format, however it does not specify the criteria
to be followed for writing testable specifications; i.e. specifications that
can be used to for the semantic description of low level requirements.
Please, for any future versions, stick to the 80-column limit; this is
especially important for text files that you want humans to read.
As a nit, you don't need to start by saying what other documents don't
do, just describe the purpose of *this* document.
More substantially ... I got a way into this document before realizing
that you were describing an addition to the format of kerneldoc
comments. That would be good to make clear from the outset.
What I still don't really understand is what is the *purpose* of this
formalized text? What will be consuming it? You're asking for a fair
amount of effort to write and maintain these descriptions; what's in it
for the people who do that work?
I might be wrong, but sounds to me like someone intends to feed this to
AI to generate tests or code.
Absolutely not the intent. This is about the lossy process of converting human
ideas to code. Reliably going from code to test requires an understanding of
what was lost in translation. This project is about filling that gap.
Thanks for clarifying. I rang my alarm bells too early :)
I saw the LPC talk on this topic:
https://lpc.events/event/19/contributions/2085/
With things like "a test case can be derived from the testable
expectation" one wonders how we get from the the doc to an actual test case.
IIRC, with things like formal verification we usually don't write in
natural language, because it's too imprecise. But my formal verification
knowledge is a bit rusty.
In that case, no thanks.
I'm pretty sure we don't want this.
Nor I. If you find any references in our work that amount to a validation of
your concerns, please bring them to our attention.
I guess, as the discussion with me and Jonathan showed, the cover letter
is a bit short on the motivation, making people like me speculate a bit
too much about the intentions.
--
Cheers
David / dhildenb
