Re: [PATCH] usb: fix some scripts/kernel-doc warnings

[Greg Kroah-Hartman <gregkh@linuxfoundation.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 <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