From da70b8c47515ea408e3ab7fd97307ef16d3b9ff1 Mon Sep 17 00:00:00 2001 From: Matthew Wilcox Date: Tue, 13 Feb 2018 13:15:33 -0800 Subject: [PATCH] Add documentation for Context section This section is mentioned in scripts/kernel-doc, so we should mention it in doc-guide/kernel-doc.rst. There are close to 500 comments using the Context section already, and almost 300 using a Locking section which fulfills much the same purpose (and should probably be converted for consistency). Signed-off-by: Matthew Wilcox Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 722d4525f7cf..315b0ecc7a11 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -117,6 +117,7 @@ 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 argument1, char *argument2) @@ -216,6 +217,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, + * releases, or expects to be held. It can extend over multiple + * lines. * Return: Describe the return value of foobar. * * The return value description can also have multiple paragraphs, and should @@ -226,6 +230,24 @@ The brief description following the function name may span multiple lines, and ends with an argument description, a blank comment line, or the end of the comment block. +Function context +~~~~~~~~~~~~~~~~ + +The context in which a function can be called should be described in a +section named ``Context``. This should 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. + +Examples:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases . + * Context: Softirq or process context. Takes and releases , BH-safe. + * Context: Interrupt context. + Return values ~~~~~~~~~~~~~ @@ -347,6 +369,9 @@ Typedefs with function prototypes can also be documented:: * @arg2: description of arg2 * * Description of the type. + * + * Context: Locking context. + * Return: Meaning of the return value. */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); -- 2.30.2