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

[Tobin C. Harding]

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?

thanks,
Tobin.