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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Tue, 6 Aug 2013 06:28:29 +0800
From:	Greg Kroah-Hartman <gregkh@...uxfoundation.org>
To:	Yacine Belkadi <yacine.belkadi.1@...il.com>
Cc:	Alan Stern <stern@...land.harvard.edu>,
	Jiri Kosina <jkosina@...e.cz>,
	Sarah Sharp <sarah.a.sharp@...ux.intel.com>,
	Kevin Hilman <khilman@...aro.org>,
	Alexey Khoroshilov <khoroshilov@...ras.ru>,
	Thomas Renninger <trenn@...e.de>,
	Hannes Reinecke <hare@...e.de>,
	Lan Tianyu <tianyu.lan@...el.com>,
	Sebastian Andrzej Siewior <bigeasy@...utronix.de>,
	Ming Lei <ming.lei@...onical.com>,
	Tülin İzer <tulinizer@...il.com>,
	Sachin Kamat <sachin.kamat@...aro.org>,
	Johan Hovold <jhovold@...il.com>, Kay Sievers <kay@...y.org>,
	Julius Werner <jwerner@...omium.org>,
	Yuanhan Liu <yliu.null@...il.com>, linux-usb@...r.kernel.org,
	linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org
Subject: Re: [PATCH] usb: fix some scripts/kernel-doc warnings

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@...il.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@...ux-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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/