Skip to contentSkip to conversation

doc: document the kernel-doc conventions for kernel hackers

PATCH Superseded Paul Jackson 2 participants 2 messages May 30, 2008 Documentation

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

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.

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 +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.1373
#1 lore raw
Quoted 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.

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?"