[PATCH 03/12] staging: ks7010: convert comments to kernel doc format

[Greg Kroah-Hartman]

On Tue, Mar 14, 2017 at 12:39:46PM +1100, Tobin C. Harding wrote:
> On Tue, Mar 14, 2017 at 08:06:18AM +0800, Greg Kroah-Hartman wrote:
> > On Tue, Mar 14, 2017 at 09:54:01AM +1100, Tobin C. Harding wrote:
> > > Function comments use a custom format. We have a standard function
> > > comment format, kernel doc format. Using the standard format aids
> > > readability and allows documentation to be produced using kernel
> > > tools.
> > > 
> > > Convert function comments to use kernel doc format.
> > > 
> > > Signed-off-by: Tobin C. Harding <me at tobin.cc>
> > > ---
> > >  drivers/staging/ks7010/ks_wlan_net.c | 554 +++++++++++++++++++++++++----------
> > >  1 file changed, 395 insertions(+), 159 deletions(-)
> > > 
> > > diff --git a/drivers/staging/ks7010/ks_wlan_net.c b/drivers/staging/ks7010/ks_wlan_net.c
> > > index 1ff1948..c6f891e 100644
> > > --- a/drivers/staging/ks7010/ks_wlan_net.c
> > > +++ b/drivers/staging/ks7010/ks_wlan_net.c
> > > @@ -163,8 +163,7 @@ int ks_wlan_setup_parameter(struct ks_wlan_private *priv,
> > >  	return 0;
> > >  }
> > >  
> > > -/*
> > > - * Initial Wireless Extension code for Ks_Wlannet driver by :
> > > +/* Initial Wireless Extension code for Ks_Wlannet driver by :
> > >   *	Jean Tourrilhes <jt at hpl.hp.com> - HPL - 17 November 00
> > >   * Conversion to new driver API by :
> > >   *	Jean Tourrilhes <jt at hpl.hp.com> - HPL - 26 March 02
> > > @@ -173,8 +172,11 @@ int ks_wlan_setup_parameter(struct ks_wlan_private *priv,
> > >   * would not work at all... - Jean II
> > >   */
> > >  
> > > -/*------------------------------------------------------------------*/
> > > -/* Wireless Handler : get protocol name */
> > > +/**
> > > + * ks_wlan_get_name() - Get protocol name.
> > > + *
> > > + * Wireless Handler
> > > + */
> > >  static int ks_wlan_get_name(struct net_device *dev,
> > 
> > static functions never need to be converted to kerneldoc, as no
> > documentation would need to be created for them.
> > 
> > All that needs to be done here is, at the most:
> > /* get protocol name */
> > 
> > But really, given that the function name is pretty good, there's no need
> > for a comment about it at all, right?
> > 
> > Same for lots of other ones in this patch.
> 
> Righto. What about the 'Wireless Handler' and 'Private Handler'. If we
> remove the comment won't that be some loss of information?

Do they actually make any sense?  Not to me...