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

[Gabriele Paoloni]

Hi Greg

thanks for the quick response

On Thu, Feb 12, 2026 at 1:59 PM Greg KH <gregkh@xxxxxxxxxxxxxxxxxxx> wrote:
>
> 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@xxxxxxxxxx>
> > ---
> >  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?

The idea is to have a specific behaviour or constraint of use
identified by the tuple [function_name behavior][ID].
So I think we could have a problem for duplicated symbols (but
it is a sort of corner case...)

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

I thought that there is no need to specify an ID format as long as the ID is
unique and referenced by the kunit tests testing the symbol.
Basically I thought that in some cases it is easier to enumerate 1, 2, 3,
whereas in others a, b, c can be used or even a mix 1a, 1b, 2a, 2b etc.
So I wanted to leave such freedom to the programmer.

>
> 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.

Well given that the tested ids are defined by the tuples mentioned above,
the relation between a kunit test and the tested tuples should be not
ambiguous.
Also I thought that, when writing a kunit test, the tester should know which
behavior is being tested and hence it should be easy to define the tested
tuples in the kunit header.
So I do not see much of a burden, but maybe I am missing something here...

Gab

>
> That's just not going to work, sorry.
>
> greg k-h
>