| Message ID | 20090623075024.66ac5d70@pedra.chehab.org (mailing list archive) |
|---|---|
| State | RFC |
| Headers | show |
Mauro, Thanks. I have sent a patch yesterday for TVP514x that fixes the comment formatting. Please review that when you get a chance. Murali Karicheri Software Design Engineer Texas Instruments Inc. Germantown, MD 20874 Phone : 301-515-3736 email: m-karicheri2@ti.com >-----Original Message----- >From: Mauro Carvalho Chehab [mailto:mchehab@redhat.com] >Sent: Tuesday, June 23, 2009 6:50 AM >To: Karicheri, Muralidharan >Cc: Hans Verkuil; linux-media@vger.kernel.org >Subject: Re: [PULL] http://www.linuxtv.org/hg/~hverkuil/v4l-dvb-vpfe-cap > >Em Mon, 22 Jun 2009 11:02:58 -0500 >"Karicheri, Muralidharan" <m-karicheri2@ti.com> 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@oracle.com> >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@oracle.com> > Reported-by: Robert Love <robert.w.love@intel.com> > Signed-off-by: Andrew Morton <akpm@linux-foundation.org> > Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org> > >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@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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.