Hi Jonathan
Many thanks for your review
On Tue, Sep 16, 2025 at 12:34 AM Jonathan Corbet corbet@lwn.net wrote:
Gabriele Paoloni gpaoloni@redhat.com writes:
[Taking a quick look...]
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 gpaoloni@redhat.com Signed-off-by: Chuck Wolber chuckwolber@gmail.com Signed-off-by: Kate Stewart kstewart@linuxfoundation.org
.../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.rst
diff --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.
Thanks I will stick to 80 chars for future submissions
As a nit, you don't need to start by saying what other documents don't do, just describe the purpose of *this* document.
Yes, my goal was to explain the purpose of this doc, however, re-reading this intro I realize that it uses a negative tone, that is not good. I will rephrase explaining the it expands on top of kernel-doc.rst to further specify the expectations from the code and the assumptions to correctly use it.
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?
The goal is to clearly define what the code is expected to do and how to correctly invoke it so that: 1) A user of the code does not wrongly invoke it 2) A developer or a maintainer can check if code changes are compliant with such expectations (maybe he did wrong changes or the expectations need to change) 3) A tester can verify if test cases are correct WRT such expectations and complete
How does an author determine whether the specifications they have written are correct, both gramatically and semantically?
For grammatical purpose, probably an automated check could be implemented, for semantic aspects the first level of verification comes from the community and maintainer review process, whereas the second level of verification come from selftests that should be written according to the expectations from the code and should trace to them (as in the example in patch 3)
Thanks Gab
Thanks,
jon