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

[Lee Jones]

On Tue, 01 Dec 2020, Daniel Vetter wrote:

> On Tue, Dec 1, 2020 at 10:46 AM Lee Jones <lee.jones at linaro.org> wrote:
> >
> > 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.
> 
> Personally what I've done is to just remove the kerneldoc marker (and
> anything else that's obviously wrong) and leave plain comments behind.
> At least for old outdated code that no one actively maintains anymore.
> Keeps the comment as maybe something useful, and avoids pointless busy
> work of inventing kerneldoc which might or might not actually be
> correctly describing what's going on.

Right.  Demoting is also a good option if in doubt.

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