Re: [PATCH] powerpc: Xilinx: PS2: Added new XPS PS2 driver

[Grant Likely <grant.likely@secretlab.ca>]

On Mon, Jun 30, 2008 at 02:10:23PM -0400, Dmitry Torokhov wrote:
> Hi Grant, John,
> 
> On Mon, Jun 30, 2008 at 11:16:28AM -0600, Grant Likely wrote:
> > On Mon, Jun 30, 2008 at 07:24:48AM -0700, John Linn wrote:
<snip>
> > > +/*
> > > + * sxps2_write() sends a byte out through the PS/2 interface.
> > > + *
> > > + * The sole purpose of drvdata->tx_end is to prevent the driver
> > > + * from locking up in the do {} while; loop when nothing is connected
> > > + * to the given PS/2 port. That's why we do not try to recover
> > > + * from the transmission failure.
> > > + * drvdata->tx_end needs not to be initialized to some "far in the
> > > + * future" value, as the very first attempt to xps2_send() a byte
> > > + * is always successful, and drvdata->tx_end will be set to a proper
> > > + * value at that moment - before the 1st use in the comparison.
> > > + */
> > 
> > Good comment block.
> > 
> > nitpick: can you reformat the comment blocks to be in kerneldoc format?
> > That will allow the automatic document generation tools to parse it.
> > 
> > see: Documentation/kernel-doc-nano-HOWTO.txt
> 
> This is an internal function so its not going to be exposed in
> kerneldoc though.

Just to complete this discussion, quoting from kernel-doc-nano-HOWTO.txt:

  "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."

but it's just a nitpick, and I'll say nothing more about it.

g.