All of lore.kernel.org
 help / color / mirror / Atom feed
From: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
To: "Tobin C. Harding" <me@tobin.cc>
Cc: driverdev-devel@linuxdriverproject.org, Wolfram Sang <wsa@the-dreams.de>
Subject: Re: [PATCH 03/12] staging: ks7010: convert comments to kernel doc format
Date: Tue, 14 Mar 2017 09:41:57 +0800	[thread overview]
Message-ID: <20170314014157.GA31864@kroah.com> (raw)
In-Reply-To: <20170314013946.GA25311@eros>

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@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@hpl.hp.com> - HPL - 17 November 00
> > >   * Conversion to new driver API by :
> > >   *	Jean Tourrilhes <jt@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...
_______________________________________________
devel mailing list
devel@linuxdriverproject.org
http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel

  reply	other threads:[~2017-03-14  1:42 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-03-13 22:53 [PATCH 00/12] staging: ks7010: fix checkpatch ks_wlan_net.c Tobin C. Harding
2017-03-13 22:53 ` [PATCH 01/12] staging: ks7010: fix checkpatch SPACING Tobin C. Harding
2017-03-13 22:54 ` [PATCH 02/12] staging: ks7010: fix checkpatch BLOCK_COMMENT_STYLE Tobin C. Harding
2017-03-13 22:54 ` [PATCH 03/12] staging: ks7010: convert comments to kernel doc format Tobin C. Harding
2017-03-14  0:06   ` Greg Kroah-Hartman
2017-03-14  1:39     ` Tobin C. Harding
2017-03-14  1:41       ` Greg Kroah-Hartman [this message]
2017-03-13 22:54 ` [PATCH 04/12] staging: ks7010: fix logical line continuation Tobin C. Harding
2017-03-13 22:54 ` [PATCH 05/12] staging: ks7010: remove dead code Tobin C. Harding
2017-03-13 22:54 ` [PATCH 06/12] staging: ks7010: remove multiple assignment Tobin C. Harding
2017-03-13 22:54 ` [PATCH 07/12] staging: ks7010: move comparison to right hand side Tobin C. Harding
2017-03-14  9:17   ` Dan Carpenter
2017-03-14 10:42     ` Tobin C. Harding
2017-03-13 22:54 ` [PATCH 08/12] staging: ks7010: remove unnecessary else statement Tobin C. Harding
2017-03-14  9:23   ` Dan Carpenter
2017-03-14 10:54     ` Tobin C. Harding
2017-03-14 11:18       ` Dan Carpenter
2017-03-14 20:34         ` Tobin C. Harding
2017-03-13 22:54 ` [PATCH 09/12] staging: ks7010: remove unnecessary cast Tobin C. Harding
2017-03-14  0:07   ` Greg Kroah-Hartman
2017-03-14  1:41     ` Tobin C. Harding
2017-03-13 22:54 ` [PATCH 10/12] staging: ks7010: fix checkpatch memset warning Tobin C. Harding
2017-03-14  9:27   ` Dan Carpenter
2017-03-14 10:44     ` Tobin C. Harding
2017-03-14 11:08       ` Dan Carpenter
2017-03-13 22:54 ` [PATCH 11/12] staging: ks7010: reduce level of indentation Tobin C. Harding
2017-03-13 22:54 ` [PATCH 12/12] staging: ks7010: refactor, whitespace only Tobin C. Harding

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170314014157.GA31864@kroah.com \
    --to=gregkh@linuxfoundation.org \
    --cc=driverdev-devel@linuxdriverproject.org \
    --cc=me@tobin.cc \
    --cc=wsa@the-dreams.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.