From: Matthew Wilcox <mawilcox@xxxxxxxxxxxxx> Let's try to be consistent and copy each other's best practices. Signed-off-by: Matthew Wilcox <mawilcox@xxxxxxxxxxxxx> --- Documentation/doc-guide/kernel-doc.rst | 42 ++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/Documentation/doc-guide/kernel-doc.rst b/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 ``file`` +(unless you have a good reason to use another name) and document it like +this:: + + * @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 ============================= -- 2.15.1 -- 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
