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? Thanks, Yacine -- 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
