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@xxxxxxxxx> > >>>> --- > >>>> > >>>> 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@xxxxxxxxxxxxxxxxxxxx> > >> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
