Hi Greg thanks for the quick response
On Thu, Feb 12, 2026 at 1:59 PM Greg KH <[email protected]> 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 <[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? 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 >
