On Tue, Dec 1, 2020 at 10:46 AM Lee Jones lee.jones@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