Gabriele Paoloni <[email protected]> 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 <[email protected]> > Signed-off-by: Chuck Wolber <[email protected]> > Signed-off-by: Kate Stewart <[email protected]> > --- > .../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. 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
