From: Matthew Wilcox <mawilcox@xxxxxxxxxxxxx>
The scripts/kernel-doc processor mentions the ability to add arbitrary
section names and suggests including a Context: section. We already
have about 450 Context: sections in the kernel, so document it.
We also have around 250 Locking: sections in the kernel ... these should
probably all be renamed for consistency.
Signed-off-by: Matthew Wilcox <mawilcox@xxxxxxxxxxxxx>
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 0268335414ce..c347f5a81cd3 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -116,6 +116,8 @@ Example kernel-doc function comment::
*
* Longer description of foobar.
*
+ * Context: Interrupt / locking context of foobar.
+ *
* Return: Description of return value of foobar.
*/
int foobar(int arg)
@@ -220,6 +222,9 @@ The general format of a function and function-like macro kernel-doc comment is::
*
* The longer description may have multiple paragraphs.
*
+ * Context: Describes whether the function can sleep, what locks it takes
+ * or releases, or expects to be held.
+ *
* Return: Describe the return value of foobar.
*
* The return value description can also have multiple paragraphs, and should
@@ -238,6 +243,11 @@ descriptions may span multiple lines. The continuation lines may contain
indentation. If a function parameter is ``...`` (varargs), it should be listed
in kernel-doc notation as: ``@...:``.
+The context in which a function can be called should be documented in a
+"Context:" section. Ideally, this will include whether the function
+sleeps or can be called from interrupt context, as well as what locks
+it takes, releases and expects to be held by its caller.
+
The return value, if any, should be described in a dedicated section at the end
of the comment starting with "Return:".
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
