Re: [PATCH v2 13/28] video: fbdev: riva: Fix kernel-doc and set but not used warnings

From: Lee Jones <lee.jones@linaro.org>
To: Sam Ravnborg <sam@ravnborg.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>,
	linux-fbdev@vger.kernel.org, dri-devel@lists.freedesktop.org,
	Vaibhav Gupta <vaibhavgupta40@gmail.com>,
	Tetsuo Handa <penguin-kernel@i-love.sakura.ne.jp>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Jiri Slaby <jirislaby@kernel.org>, Arnd Bergmann <arnd@arndb.de>,
	Florian Tobias Schandinat <FlorianSchandinat@gmx.de>,
	Evgeny Novikov <novikov@ispras.ru>,
	Saeed Mirzamohammadi <saeed.mirzamohammadi@oracle.com>,
	Daniel Vetter <daniel.vetter@ffwll.ch>,
	Thomas Winischhofer <thomas@winischhofer.net>,
	Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>,
	Jani Nikula <jani.nikula@intel.com>,
	Aditya Pakki <pakki001@umn.edu>,
	Xiaofei Tan <tanxiaofei@huawei.com>,
	Nathan Chancellor <natechancellor@gmail.com>,
	Alex Dewar <alex.dewar90@gmail.com>,
	Jason Yan <yanaijie@huawei.com>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Qilong Zhang <zhangqilong3@huawei.com>,
	Randy Dunlap <rdunlap@infradead.org>,
	Gustavo Silva <gustavoars@kernel.org>,
	Peter Rosin <peda@axentia.se>,
	George Kennedy <george.kennedy@oracle.com>,
	Kristoffer Ericson <kristoffer.ericson@gmail.com>,
	Alexander Klimov <grandmaster@al2klimov.de>,
	Jingoo Han <jingoohan1@gmail.com>, Joe Perches <joe@perches.com>,
	Peilin Ye <yepeilin.cs@gmail.com>,
	Mike Rapoport <rppt@kernel.org>
Subject: Re: [PATCH v2 13/28] video: fbdev: riva: Fix kernel-doc and set but not used warnings
Date: Tue, 1 Dec 2020 09:46:29 +0000	[thread overview]
Message-ID: <20201201094629.GG4801@dell> (raw)
In-Reply-To: <20201201090745.GA1980788@ravnborg.org>

On Tue, 01 Dec 2020, Sam Ravnborg wrote:

> Hi Lee,
> 
> > 
> > Cop-out!
> > 
> > Do what I do and make something up (joke)! :'D
> 
> If I thought anyone would actually read the comments then maybe yes.
> But I assume that apart from this thread no-one will read it.
> 
> > 
> > > > Well, it fixes the warning ;)
> > > 
> > > Yeah, I could not dig up anything useful to say here.
> > > Was tempted to just drop all the kernel-doc syntax but that
> > > was a larger change.
> > 
> > Did you trace it from it's origin down to it's final use?
> Yeah, but not something that seemed useful.
> I could have added "translating from pixels->bytes" as they
> are described somewhere else. But I could not convince myself
> this was right so I just silenced the warning.
> 
> The only reason I kept the kernel-doc in the first place is
> that I am told some editors use it.
> 
> The only effect the kernel-doc in fbdev has right now is burning
> effort that could have been spent (better?) somewhere else, and
> I would personally prefer to drop the kernel-doc annotations.
> 
> But I already discussed this in another thread (not fbdev related)
> and I was told it was useful for some, so it is kept.

I personally think they should be kept.  Despite not being referenced
by any kernel-doc:: key-words.  As you say, it can be helpful as an
in-code reference for driver writers, people debugging code, et al.

Not sure I would just repeat the variable name just to silence the
warning though - that is definitely a hack.  In the thousands
(literally!) of these that I've fixed thus far, I haven't needed to do
that.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog