Re: [RFC v2 PATCH 1/3] Documentation: add guidelines for writing testable code specifications
From: Jonathan Corbet <corbet@lwn.net>
Date: 2025-09-15 22:33:59
Also in:
linux-kselftest, linux-mm, lkml
Gabriele Paoloni [off-list ref] writes: [Taking a quick look...]
quoted hunk ↗ jump to hunk
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. This patch adds a guideline that defines criteria to formally describe developers’ intent at the function and subfunction level in the form of testable expectations. Signed-off-by: Gabriele Paoloni <redacted> Signed-off-by: Chuck Wolber <redacted> Signed-off-by: Kate Stewart <redacted> --- .../doc-guide/code-specifications.rst | 208 ++++++++++++++++++ Documentation/doc-guide/index.rst | 1 + 2 files changed, 209 insertions(+) create mode 100644 Documentation/doc-guide/code-specifications.rstdiff --git a/Documentation/doc-guide/code-specifications.rst b/Documentation/doc-guide/code-specifications.rst new file mode 100644 index 000000000000..dee1b4f089e1 --- /dev/null +++ b/Documentation/doc-guide/code-specifications.rst@@ -0,0 +1,208 @@ +.. title:: How-to write testable code specifications + +========================================= +How-to write testable code specifications +========================================= + +Introduction +------------ +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? How does an author determine whether the specifications they have written are correct, both gramatically and semantically? Thanks, jon