From: Matthew Wilcox <>

Let's try to be consistent and copy each other's best practices.

Signed-off-by: Matthew Wilcox <>
 Documentation/doc-guide/kernel-doc.rst | 42 ++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst 
index 2fb7f2bfc245..0253e51b76cf 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -411,6 +411,48 @@ The title following ``DOC:`` acts as a heading within the 
source file, but also
 as an identifier for extracting the documentation comment. Thus, the title must
 be unique within the file.
+Style guide
+It is helpful to maintain a consistent style across the kernel.  It helps
+the reader who can rely on conventions to understand a part of the kernel
+which is new to them.  It also helps the writer who can simply copy and
+paste function parameter descriptions instead of coming up with new and
+excitingly different ways to say the same thing.
+Context names
+Refer to process context, softirq context and hardirq context.  Interrupt
+context refers to both hard and soft interrupts.  Bottom half context
+is deprecated; it is a synonym for softirq context.  Tasklet context
+should not be used; tasklets run in softirq context.  Do not use user
+context; this is a synonym for process context.
+Common function parameters
+If you pass ``GFP_`` flags to a function, name the parameter ``gfp`` and
+document it like this::
+  * @gfp: Memory allocation flags.
+If your function takes a ``struct file *`` argument, name the parameter 
+(unless you have a good reason to use another name) and document it like
+  * @file: File pointer.
+If your function takes a ``struct dentry *`` argument, name the
+parameter ``dentry`` and document it like this::
+  * @dentry: Directory Entry pointer.
+If your function takes a ``struct inode *`` argument, name the parameter
+``inode`` and document it like this::
+  * @inode: Inode pointer.
 Including kernel-doc comments

To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to
More majordomo info at

Reply via email to