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

[Yacine Belkadi]

On 08/06/2013 12:28 AM, Greg Kroah-Hartman wrote:
> 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.

Noted. 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/