From: Paul Jackson <pj@sgi.com>

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 <pj@sgi.com>
Cc: Randy Dunlap <rdunlap@xenotime.net>
Cc: Alan Cox <alan@lxorguk.ukuu.org.uk>

---
 Documentation/kernel-doc-nano-HOWTO.txt |   99 ++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

--- linux-2.6.orig/Documentation/kernel-doc-nano-HOWTO.txt	2008-05-30 08:47:13.000000000 -0700
+++ linux-2.6/Documentation/kernel-doc-nano-HOWTO.txt	2008-05-30 13:31:07.111325343 -0700
@@ -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 ...
[ message continues ]

Yes, that comment is correct.  And unfortunate.  We need some way to provide


Please fix the few typos and add Acked-by: Randy Dunlap <rdunlap@xenotime.net>.

Thanks, Paul.

---
~Randy
"He closes his eyes and drops the goggles.  You can't get hurt
by looking at a bitmap.  Or can you?"
--

[ message continues ]