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

[Yacine Belkadi]

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-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/