doc: document the kernel-doc conventions for kernel hackers
PATCH 1/1 doc: document the kernel-doc conventions for kernel hackers
From: Paul Jackson <[email protected]>
Provide documentation of the kernel-doc documentation conventions oriented to kernel hackers.
Since I figure that there will be more people reading this kernel-doc-nano-HOWTO.txt file who are kernel developers focused on the rest of the kernel, than there will be readers of this file who are documentation developers extracting that embedded kernel-doc documentation, I have taken the liberty of making the new section added here:
How to format kernel-doc comments
the first section of the kernel-doc-nano-HOWTO.txt file.
This first section is intended to introduce, motivate and provide basic usage of the kernel-doc mechanism for kernel hackers developing other portions of the kernel.
--- Documentation/kernel-doc-nano-HOWTO.txt | 99 ++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+)
Documentation/kernel-doc-nano-HOWTO.txt +99 -0
@@ -1,6 +1,105 @@ kernel-doc nano-HOWTO ===================== +How to format kernel-doc comments +--------------------------------- + +In order to provide an embedded, 'C' friendly, easy to maintain, +but consistent and extractable documentation of the functions and +data structures in the Linux kernel, the Linux kernel has adopted +a consistent style for documenting functions and their parameters, +and structures and their members. + +The format for this documentation is called the kernel-doc format. +It as documented in this Documentation/kernel-doc-nano-HOWTO.txt file. + +This style embeds the documentation within the source files, using +a few simple conventions. The scripts/kernel-doc perl script, some +SGML templates in Documentation/DocBook, and other tools understand +these conventions, and are used to extract this embedded documentation +into various documents. + +In order to provide good documentation of kernel functions and data +structures, please use the following conventions to format your +kernel-doc comments in Linux kernel source. + +We definitely need kernel-doc formatted documentation for functions +that are exported to loadable modules using EXPORT_SYMBOL. + +We also look to provide kernel-doc formatted documentation for +functions externally visible to other kernel files (not marked +"static"). + +We also recommend providing kernel-doc formatted documentation +for private (file "static") routines, for consistency of kernel +source code layout. But this is lower priority and at the +discretion of the MAINTAINER of that kernel source file. + +Data structures visible in kernel include files should also be +documented using kernel-doc formatted comments. + +The opening comment mark "/**" is reserved for kernel-doc comments. +Only comments so marked will be considered by the kernel-doc scripts, +and any comment so marked must be in kernel-doc format. Do not use +"/**" to be begin a comment block unless the comment block contains +kernel-doc formatted comments. The closing comment marker for +kernel-doc comments can be either "*/" or "**/". + +Kernel-doc comments should be placed just before the function +or data structure being describe. + +Example kernel-doc function comment: + +/** + * foobar() - short function description of foobar + * @arg1: Describe the first argument to foobar. + * @arg2: Describe the second argument to foobar. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function foobar() + * that might be useful to those using or modifying it. Begins with + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description can have multiple paragraphs. + **/ + +The first line, with the short description, must be on a single line. + +The @argument descriptions must begin on the very next line following +this opening short function description line, with no intervening +empty comment lines. + +Example kernel-doc data structure comment. + +/** + * struct blah - the basic blah structure + * @mem1: describe the first member of struct blah + * @mem2: describe the second member of struct blah, + * perhaps with more lines and words. + * + * Longer description of this structure. + **/ + +The kernel-doc function comments describe each parameter to the +function, in order, with the @name lines. + +The kernel-doc data structure comments describe each structure member +in the data structure, with the @name lines. + +The longer description formatting is "reflowed", loosing your line +breaks. So presenting carefully formatted lists within these +descriptions won't work so well; derived documentation will loose +the formatting. + +See the section below "How to add extractable documentation to your +source files" for more details and notes on how to format kernel-doc +comments. + +Components of the kernel-doc system +----------------------------------- + Many places in the source tree have extractable documentation in the form of block comments above functions. The components of this system are:
Signature · 3 lines
I won't rest till it's the best ...
Programmer, Linux Scalability
Paul Jackson <[email protected]> 1.650.933.1373Quoted 70 lines · On Fri, 30 May 2008 13:34:42 -0700 Paul Jackson wrote:
From: Paul Jackson <[email protected]>
Provide documentation of the kernel-doc documentation conventions oriented to kernel hackers.
Since I figure that there will be more people reading this kernel-doc-nano-HOWTO.txt file who are kernel developers focused on the rest of the kernel, than there will be readers of this file who are documentation developers extracting that embedded kernel-doc documentation, I have taken the liberty of making the new section added here:
How to format kernel-doc comments
the first section of the kernel-doc-nano-HOWTO.txt file.
This first section is intended to introduce, motivate and provide basic usage of the kernel-doc mechanism for kernel hackers developing other portions of the kernel.
Signed-off-by Paul Jackson <[email protected]>Cc Randy Dunlap <[email protected]>Cc Alan Cox <[email protected]>--- Documentation/kernel-doc-nano-HOWTO.txt | 99 ++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+)Documentation/kernel-doc-nano-HOWTO.txt +36
-0@@ -1,6 +1,105 @@ kernel-doc nano-HOWTO ===================== +How to format kernel-doc comments +--------------------------------- + +In order to provide an embedded, 'C' friendly, easy to maintain, +but consistent and extractable documentation of the functions and +data structures in the Linux kernel, the Linux kernel has adopted +a consistent style for documenting functions and their parameters, +and structures and their members. + +The format for this documentation is called the kernel-doc format. +It as documented in this Documentation/kernel-doc-nano-HOWTO.txt file. + +This style embeds the documentation within the source files, using +a few simple conventions. The scripts/kernel-doc perl script, some +SGML templates in Documentation/DocBook, and other tools understand +these conventions, and are used to extract this embedded documentation +into various documents. + +In order to provide good documentation of kernel functions and data +structures, please use the following conventions to format your +kernel-doc comments in Linux kernel source. + +We definitely need kernel-doc formatted documentation for functions +that are exported to loadable modules using EXPORT_SYMBOL. + +We also look to provide kernel-doc formatted documentation for +functions externally visible to other kernel files (not marked +"static"). + +We also recommend providing kernel-doc formatted documentation +for private (file "static") routines, for consistency of kernel +source code layout. But this is lower priority and at the +discretion of the MAINTAINER of that kernel source file. + +Data structures visible in kernel include files should also be +documented using kernel-doc formatted comments.
Documentation/kernel-doc-nano-HOWTO.txt line 49
Quoted 10 lines
Documentation/kernel-doc-nano-HOWTO.txt +10
-0+ +The opening comment mark "/**" is reserved for kernel-doc comments. +Only comments so marked will be considered by the kernel-doc scripts, +and any comment so marked must be in kernel-doc format. Do not use +"/**" to be begin a comment block unless the comment block contains +kernel-doc formatted comments. The closing comment marker for +kernel-doc comments can be either "*/" or "**/". + +Kernel-doc comments should be placed just before the function +or data structure being describe.
described.
Quoted 19 lines
Documentation/kernel-doc-nano-HOWTO.txt +19
-0+ +Example kernel-doc function comment: + +/** + * foobar() - short function description of foobar + * @arg1: Describe the first argument to foobar. + * @arg2: Describe the second argument to foobar. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function foobar() + * that might be useful to those using or modifying it. Begins with + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description can have multiple paragraphs. + **/ + +The first line, with the short description, must be on a single line.
Documentation/kernel-doc-nano-HOWTO.txt line 78
Quoted 10 lines
Documentation/kernel-doc-nano-HOWTO.txt +10
-0+ +The @argument descriptions must begin on the very next line following +this opening short function description line, with no intervening +empty comment lines. + +Example kernel-doc data structure comment. + +/** + * struct blah - the basic blah structure + * @mem1: describe the first member of struct blah
Use tab or space(s) after @memN: consistently, please.
Documentation/kernel-doc-nano-HOWTO.txt line 91
Quoted 13 lines
Documentation/kernel-doc-nano-HOWTO.txt +13
-0+ * @mem2: describe the second member of struct blah, + * perhaps with more lines and words. + * + * Longer description of this structure. + **/ + +The kernel-doc function comments describe each parameter to the +function, in order, with the @name lines. + +The kernel-doc data structure comments describe each structure member +in the data structure, with the @name lines. + +The longer description formatting is "reflowed", loosing your line
losing
Documentation/kernel-doc-nano-HOWTO.txt line 93
Quoted 2 lines
Documentation/kernel-doc-nano-HOWTO.txt +2
-0+breaks. So presenting carefully formatted lists within these +descriptions won't work so well; derived documentation will loose
lose
Documentation/kernel-doc-nano-HOWTO.txt line 94
Quoted 1 line
Documentation/kernel-doc-nano-HOWTO.txt +1
-0+the formatting.
Yes, that comment is correct. And unfortunate. We need some way to provide a simple formatted list.
Documentation/kernel-doc-nano-HOWTO.txt line 105
Quoted 11 lines
Documentation/kernel-doc-nano-HOWTO.txt +8
-0+ +See the section below "How to add extractable documentation to your +source files" for more details and notes on how to format kernel-doc +comments. + +Components of the kernel-doc system +----------------------------------- + Many places in the source tree have extractable documentation in the form of block comments above functions. The components of this system are:
Please fix the few typos and add Acked-by: Randy Dunlap <[email protected]>.
Thanks, Paul.
---
~Randy
"He closes his eyes and drops the goggles. You can't get hurt by looking at a bitmap. Or can you?"