Re: [PATCH 3/3] fcoe: Fibre Channel over Ethernet

[Andrew Morton <akpm@linux-foundation.org>]

On Fri, 06 Feb 2009 11:05:17 -0800
Robert Love <robert.w.love@intel.com> wrote:

> > The kerneldoc comments consistently close with
> > 
> > **/
> > 
> > which is consistently unconventional.  Not wrong, just odd.
> > 
> 
> I did change the kernel-doc function comment blocks to end with '*/',
> since you called it out. I looked at the other comments under
> drivers/scsi/ and most did end in '*/'. However, the
> Documentation/kernel-doc-nano-HOWTO.txt has an example for function
> headers that shows '**/' as the suggested style. Should the kernel-doc
> HOWTO be updated?

I think so - we might as well be consistent about these things.

> 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.
>  **/

That's RandyStuff.