lkml.org 
[lkml]   [2013]   [Aug]   [5]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] usb: fix some scripts/kernel-doc warnings
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 <yacine.belkadi.1@gmail.com>
> >>>> ---
> >>>>
> >>>> 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 <torvalds@linux-foundation.org>
> >> 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


\
 
 \ /
  Last update: 2013-08-06 01:21    [W:0.064 / U:0.112 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site