On Fri, 30 May 2008 13:34:42 -0700 Paul Jackson wrote:
quoted text > 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 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.
described.
quoted text > +
> +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
Use tab or space(s) after @memN: consistently, please.
quoted text > + * @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
quoted text > +breaks. So presenting carefully formatted lists within these
> +descriptions won't work so well; derived documentation will loose
lose
quoted text > +the formatting.
Yes, that comment is correct. And unfortunate. We need some way to provide
a simple formatted list.
quoted text > +
> +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 <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?"
--
unsubscribe notice To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to
majordomo@vger.kernel.org
More majordomo info at
http://vger.kernel.org/majordomo-info.html
Please read the FAQ at
http://www.tux.org/lkml/ Messages in current thread:
Re: [PATCH] doc: document the kernel-doc conventions for k ... , Randy Dunlap , (Fri May 30, 2:14 pm)
