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

[Gabriele Paoloni <gpaoloni@redhat.com>]

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]
+   *
    * 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