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

[Robert Love <robert.w.love@intel.com>]

On Wed, 2009-02-04 at 18:24 -0800, Andrew Morton wrote:
> On Tue, 09 Dec 2008 15:10:24 -0800 Robert Love <robert.w.love@intel.com> wrote:
> 
> > Encapsulation protocol for running Fibre Channel over Ethernet interfaces.
> > Creates virtual Fibre Channel host adapters using libfc.
> > 
> > This layer is the LLD to the scsi-ml. It allocates the Scsi_Host, utilizes
> > libfc for Fibre Channel protocol processing and interacts with netdev to
> > send/receive Ethernet packets.
> > 
> 
> I stumbled across this while looking for new and weird kthread API usages..
> 
I just sent a patchset of Open-FCoE updates to linux-scsi. Patches in
that set should take care of the kernel-doc issues, the initialization
ordering problem for fcoe transports, the typos, the timer comments, and
the unnecessary casting problem.

> > ...
> >
> > +/**
> > + * fcoe_transport_lookup - check if the transport is already registered
> > + * @t: the transport to be looked up
> > + *
> > + * This compares the parent device (pci) vendor and device id
> > + *
> > + * Returns: NULL if not found
> > + *
> > + * TODO - return default sw transport if no other transport is found
> > + **/
> 
> 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?

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