Em Mon, 22 Jun 2009 11:02:58 -0500
"Karicheri, Muralidharan" <m-karicheri2@xxxxxx> escreveu:
> Hi,
>
> <Snip>
> >> >
> >> > -/**
> >> > +/*
> >> > * struct tvp514x_decoder - TVP5146/47 decoder object
> >> > - * @v4l2_int_device: Slave handle
> >> > - * @tvp514x_slave: Slave pointer which is used by @v4l2_int_device
> >> > + * @sd: Subdevice Slave handle
> >> > * @tvp514x_regs: copy of hw's regs with preset values.
> >> > * @pdata: Board specific
> >> > - * @client: I2C client data
> >> > - * @id: Entry from I2C table
> >> > * @ver: Chip version
> >> > - * @state: TVP5146/47 decoder state - detected or not-detected
> >> > + * @streaming: TVP5146/47 decoder streaming - enabled or disabled.
> >> > * @pix: Current pixel format
> >> > * @num_fmts: Number of formats
> >> > * @fmt_list: Format list
> >> > * @current_std: Current standard
> >> > * @num_stds: Number of standards
> >> > * @std_list: Standards list
> >> > - * @route: input and output routing at chip level
> >> > + * @input: Input routing at chip level
> >> > + * @output: Output routing at chip level
> >> > */
> >> >
> >> > Please read Documentation/kernel-doc-nano-HOWTO.txt for the proper
> >> > format. Basically, it should be like this example:
> >> >
> >> > /**
> >> > * 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.
> >> > **/
> >> >
> But kernel-doc-nano-HOWTO.txt says it should be of the form
> /**
> * 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.
> */
>
> Only one * followed by slash as */, not **/ as you have mentioned.
> Please confirm so that I can send you a patch to correct this.
You're right. It seems that I was using an older version of the doc, since it
used to be like above, on the past versions of the doc:
commit f40b45a2e45b0f02aeedfcfbb28d8e2d4b8b86b1
Author: Randy Dunlap <randy.dunlap@xxxxxxxxxx>
Date: Wed Feb 11 13:04:31 2009 -0800
kernel-doc: preferred ending marker and examples
Fix kernel-doc-nano-HOWTO.txt to use */ as the ending marker in kernel-doc
examples and state that */ is the preferred ending marker.
Signed-off-by: Randy Dunlap <randy.dunlap@xxxxxxxxxx>
Reported-by: Robert Love <robert.w.love@xxxxxxxxx>
Signed-off-by: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
Signed-off-by: Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx>
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index d73fbd2..026ec7d 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -43,7 +43,8 @@ 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 can be either "*/" or "**/", but "*/" is
+preferred in the Linux kernel tree.
Kernel-doc comments should be placed just before the function
or data structure being described.
@@ -63,7 +64,7 @@ Example kernel-doc function comment:
* comment lines.
*
* The longer description can have multiple paragraphs.
- **/
+ */
The first line, with the short description, must be on a single line.
@@ -85,7 +86,7 @@ Example kernel-doc data structure comment.
* 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.
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
