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 <[email protected]> > --- > 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
