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] + * * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. -- 2.48.1
