Hi David On Tue, Oct 21, 2025 at 5:37 PM David Hildenbrand <[email protected]> wrote: > > 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.
Probably it is the term derived that can be a bit misleading. The point is that we need documented expectations that can be used to review and verify the test cases against; so maybe better to say "a test case can be verified against the testable expectation" > > 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. Right, I'll keep this in mind for v2 and I will improve the motivation aspect (also leveraging the response I gave to Jonathan). Many thanks for your feedbacks! Gab > > -- > Cheers > > David / dhildenb >
