Re: [RFC PATCH v3 1/6] Documentation: extend the 'Function documentation' with expected behavior and constraints of use

[Greg KH <gregkh@linuxfoundation.org>]

On Thu, Feb 12, 2026 at 01:49:18PM +0100, Gabriele Paoloni wrote:
> Extend the longer description section of a function kernel-doc
> header with an itemised list of function's behaviors and
> constraints of use.
> These are useful to link and trace test cases (e.g. KUnit) to
> the different behavior IDs and define the constraints to be
> met by the function's caller.
> 
> Signed-off-by: Gabriele Paoloni <gpaoloni@redhat.com>
> ---
>  Documentation/doc-guide/kernel-doc.rst | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index 8d2c09fb36e4..23e6c4b45b14 100644
> --- a/Documentation/doc-guide/kernel-doc.rst
> +++ b/Documentation/doc-guide/kernel-doc.rst
> @@ -83,6 +83,25 @@ The general format of a function and function-like macro kernel-doc comment is::
>     *
>     * The longer description may have multiple paragraphs.
>     *
> +   * When specifying testable code behaviour the longer description must contain
> +   * a paragraph formatted as follows:
> +   *
> +   * function_name behavior:
> +   * [ID1] - [expected behavior]
> +   *
> +   * [ID2] - [expected behavior]
> +   *
> +   * [...]
> +   *
> +   * [IDn] - [expected behavior]
> +   *
> +   * function_name constraints of use:
> +   * [ID1] - [constraint to be met by the caller]
> +   *
> +   * [ID2] - [constraint to be met by the caller]
> +   *
> +   * [IDn] - [constraint to be met by the caller]

So the same "id" is used for a behavior, AND a constraint?

And what defines an "id"?  I see in your example you use number.number,
but is that specified?

And how is a id going to stay in sync across different files?  That
feels impossible to maintain for any length of time, and puts a burden
on the developer who wishes to add/remove a test or "id", AND a
maintainer who has to remember to go and look in multiple places for
such an id sync up.

That's just not going to work, sorry.

greg k-h