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

[Daniel Vetter]

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.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch