On Tue, 01 Dec 2020, Daniel Vetter wrote: > On Tue, Dec 1, 2020 at 10:46 AM Lee Jones <lee.jones@xxxxxxxxxx> 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 _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel
