Re: [RFC v2 PATCH 1/3] Documentation: add guidelines for writing testable code specifications

[Jonathan Corbet <corbet@lwn.net>]

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.

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