On Tue, 01 Dec 2020, Daniel Vetter wrote:

On Tue, Dec 1, 2020 at 10:46 AM Lee Jones [off-list ref] wrote:

quoted

On Tue, 01 Dec 2020, Sam Ravnborg wrote:

quoted

Hi Lee,

quoted

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.

quoted

quoted

quoted

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