From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from fraxinus.osuosl.org (smtp4.osuosl.org [140.211.166.137]) by ash.osuosl.org (Postfix) with ESMTP id 9571D1BFCDA for ; Tue, 14 Mar 2017 01:42:11 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id 9179B8835C for ; Tue, 14 Mar 2017 01:42:11 +0000 (UTC) Received: from fraxinus.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id dFTpmAVyLDMO for ; Tue, 14 Mar 2017 01:42:10 +0000 (UTC) Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) by fraxinus.osuosl.org (Postfix) with ESMTPS id 656EA88366 for ; Tue, 14 Mar 2017 01:42:10 +0000 (UTC) Date: Tue, 14 Mar 2017 09:41:57 +0800 From: Greg Kroah-Hartman Subject: Re: [PATCH 03/12] staging: ks7010: convert comments to kernel doc format Message-ID: <20170314014157.GA31864@kroah.com> References: <1489445650-11398-1-git-send-email-me@tobin.cc> <1489445650-11398-4-git-send-email-me@tobin.cc> <20170314000618.GA9578@kroah.com> <20170314013946.GA25311@eros> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20170314013946.GA25311@eros> List-Id: Linux Driver Project Developer List List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: driverdev-devel-bounces@linuxdriverproject.org Sender: "devel" To: "Tobin C. Harding" Cc: driverdev-devel@linuxdriverproject.org, Wolfram Sang 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 > > > --- > > > 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 - HPL - 17 November 00 > > > * Conversion to new driver API by : > > > * Jean Tourrilhes - 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