From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755641Ab3HEW1j (ORCPT ); Mon, 5 Aug 2013 18:27:39 -0400 Received: from mail.linuxfoundation.org ([140.211.169.12]:43352 "EHLO mail.linuxfoundation.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755342Ab3HEW1h (ORCPT ); Mon, 5 Aug 2013 18:27:37 -0400 Date: Tue, 6 Aug 2013 06:28:29 +0800 From: Greg Kroah-Hartman To: Yacine Belkadi Cc: Alan Stern , Jiri Kosina , Sarah Sharp , Kevin Hilman , Alexey Khoroshilov , Thomas Renninger , Hannes Reinecke , Lan Tianyu , Sebastian Andrzej Siewior , Ming Lei , =?utf-8?B?VMO8bGluIMSwemVy?= , Sachin Kamat , Johan Hovold , Kay Sievers , Julius Werner , Yuanhan Liu , linux-usb@vger.kernel.org, linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Subject: Re: [PATCH] usb: fix some scripts/kernel-doc warnings Message-ID: <20130805222829.GH20884@kroah.com> References: <1375467004-2623-1-git-send-email-yacine.belkadi.1@gmail.com> <20130803032908.GA10902@kroah.com> <51FEB410.6080909@gmail.com> <20130804212919.GA10623@kroah.com> <51FFF0B7.3080708@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <51FFF0B7.3080708@gmail.com> User-Agent: Mutt/1.5.21 (2010-09-15) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, Aug 05, 2013 at 08:36:39PM +0200, Yacine Belkadi wrote: > On 08/04/2013 11:29 PM, Greg Kroah-Hartman wrote: > > On Sun, Aug 04, 2013 at 10:05:36PM +0200, Yacine Belkadi wrote: > >> On 08/03/2013 05:29 AM, Greg Kroah-Hartman wrote: > >>> On Fri, Aug 02, 2013 at 08:10:04PM +0200, Yacine Belkadi wrote: > >>>> When building the htmldocs (in verbose mode), scripts/kernel-doc reports the > >>>> following type of warnings: > >>>> > >>>> Warning(drivers/usb/core/usb.c:76): No description found for return value of > >>>> 'usb_find_alt_setting' > >>>> > >>>> Fix them by: > >>>> - adding some missing descriptions of return values > >>>> - using "Return" sections for those descriptions > >>>> > >>>> Signed-off-by: Yacine Belkadi > >>>> --- > >>>> > >>>> Applied to b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 > >>> > >>> What does this line mean? > >> > >> It's the commit on which I created and applied the patch: > >> > >> commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6 > >> Merge: a582e5f e70e78e > >> Author: Linus Torvalds > >> Date: Mon Jul 22 19:07:24 2013 -0700 > > > > Odd, I've never seen anyone use that before. It's really not needed, so > > you don't have to do that in the future. > > > > In hindsight, I should probably have used something like: > "Patch against commit b3a3a9c441e2c8f6b6760de9331023a7906a4ac6". > > I thought this information may prove useful in some cases, because of the > nature of the patch, which only modifies comments and may get out of sync > with the code. > > Here is an example: > - My local HEAD is at commit c1 when I start creating the patch. > - Some function f doesn't have a description for its return value. I look > into the code and deduce the description. So the description I add is based > on the code at the commit c1. > - Someone else submits a patch that changes the code of the function f, but > I don't see it. > - I send my patch to the maintainer. > - My patch may apply cleanly on top of the other patch (mine only touched > the comments), but the description now doesn't match the function's code, > which is a problem. > > I assumed that if I specify the commit on which I worked, it may help the > maintainer decide whether my patch got invalidated by some other patch that > was applied first. Continuing with the example: The maintainer sees that I > worked based on c1, but knows that a patch was applied in the mean time, so > he/she asks me to update my patch first. > > What do you think? It does make sense, but please use terms that we can understand. If I see a sha id, I have to go dig through a kernel tree to see what it represents, which takes time (remember, I deal with thousands of patches). If you said "Patch based on 3.11-rc1" then I know exactly what that is, and how to handle it if there are merge errors. thanks, greg k-h