linux-fbdev.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Lee Jones <lee.jones@linaro.org>
To: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Sam Ravnborg <sam@ravnborg.org>,
	Thomas Zimmermann <tzimmermann@suse.de>,
	Linux Fbdev development list <linux-fbdev@vger.kernel.org>,
	dri-devel <dri-devel@lists.freedesktop.org>,
	Vaibhav Gupta <vaibhavgupta40@gmail.com>,
	Tetsuo Handa <penguin-kernel@i-love.sakura.ne.jp>,
	Laurent Pinchart <laurent.pinchart@ideasonboard.com>,
	Jiri Slaby <jirislaby@kernel.org>, Arnd Bergmann <arnd@arndb.de>,
	Florian Tobias Schandinat <FlorianSchandinat@gmx.de>,
	Evgeny Novikov <novikov@ispras.ru>,
	Saeed Mirzamohammadi <saeed.mirzamohammadi@oracle.com>,
	Thomas Winischhofer <thomas@winischhofer.net>,
	Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>,
	Jani Nikula <jani.nikula@intel.com>,
	Aditya Pakki <pakki001@umn.edu>,
	Xiaofei Tan <tanxiaofei@huawei.com>,
	Nathan Chancellor <natechancellor@gmail.com>,
	Alex Dewar <alex.dewar90@gmail.com>,
	Jason Yan <yanaijie@huawei.com>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Qilong Zhang <zhangqilong3@huawei.com>,
	Randy Dunlap <rdunlap@infradead.org>,
	Gustavo Silva <gustavoars@kernel.org>,
	Peter Rosin <peda@axentia.se>,
	George Kennedy <george.kennedy@oracle.com>,
	Kristoffer Ericson <kristoffer.ericson@gmail.com>,
	Alexander Klimov <grandmaster@al2klimov.de>,
	Jingoo Han <jingoohan1@gmail.com>, Joe Perches <joe@perches.com>,
	Peilin Ye <yepeilin.cs@gmail.com>,
	Mike Rapoport <rppt@kernel.org>
Subject: Re: [PATCH v2 13/28] video: fbdev: riva: Fix kernel-doc and set but not used warnings
Date: Tue, 1 Dec 2020 10:27:04 +0000	[thread overview]
Message-ID: <20201201102704.GH4801@dell> (raw)
In-Reply-To: <CAKMK7uGUJbVRVTO8xL8Kc8BbYMXzqS2KAVYL8bgex3Zz=aF9EQ@mail.gmail.com>

On Tue, 01 Dec 2020, Daniel Vetter wrote:

> 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.

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

  reply	other threads:[~2020-12-01 10:28 UTC|newest]

Thread overview: 78+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-11-28 22:40 [PATCH v2 0/28] drivers/video: W=1 warning fixes Sam Ravnborg
2020-11-28 22:40 ` [PATCH v2 01/28] video: Fix kernel-doc warnings in of_display_timing + of_videomode Sam Ravnborg
2020-11-29 10:01   ` Thomas Zimmermann
2020-11-29 11:22     ` Sam Ravnborg
2020-11-29 21:43   ` Sam Ravnborg
2020-11-28 22:40 ` [PATCH v2 02/28] video: fbcon: Fix warnings by using pr_debug() in fbcon Sam Ravnborg
2020-11-29 10:03   ` Thomas Zimmermann
2020-11-29 10:28     ` Tetsuo Handa
2020-11-29 11:18       ` Sam Ravnborg
2020-11-30  6:38         ` Peilin Ye
2020-11-30  7:56           ` Sam Ravnborg
2020-11-30  8:52             ` Peilin Ye
2020-11-29 21:45     ` Sam Ravnborg
2020-11-28 22:40 ` [PATCH v2 03/28] video: fbdev: core: Fix kernel-doc warnings in fbmon + fb_notify Sam Ravnborg
2020-11-29 10:08   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 04/28] video: fbdev: aty: Delete unused variable in radeon_monitor Sam Ravnborg
2020-11-30  8:51   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 05/28] video: fbdev: aty: Fix set but not used warnings Sam Ravnborg
2020-11-30  8:53   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 06/28] video: fbdev: aty: Fix set but not used warnings in mach64_ct Sam Ravnborg
2020-11-30  8:57   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 07/28] video: fbdev: sis: Fix defined but not used warnings Sam Ravnborg
2020-11-30  8:59   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 08/28] video: fbdev: sis: Fix defined but not used warning of SiS_TVDelay Sam Ravnborg
2020-11-30  9:13   ` Thomas Zimmermann
2020-11-30 19:01     ` Sam Ravnborg
2020-12-01  9:58       ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 09/28] video: fbdev: sis: Fix set but not used warnings in init.c Sam Ravnborg
2020-11-30  9:16   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 10/28] video: fbdev: sis: Fix set but not used warnings in sis_main Sam Ravnborg
2020-11-30 10:14   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 11/28] video: fbdev: via: Fix set but not used warning for mode_crt_table Sam Ravnborg
2020-11-30 12:08   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 12/28] video: fbdev: tdfx: Fix set but not used warning in att_outb() Sam Ravnborg
2020-11-30 12:12   ` Thomas Zimmermann
2020-11-28 22:40 ` [PATCH v2 13/28] video: fbdev: riva: Fix kernel-doc and set but not used warnings Sam Ravnborg
2020-11-30 12:14   ` Thomas Zimmermann
2020-11-30 18:35     ` Sam Ravnborg
2020-12-01  8:47       ` Lee Jones
2020-12-01  9:07         ` Sam Ravnborg
2020-12-01  9:46           ` Lee Jones
2020-12-01 10:04             ` Daniel Vetter
2020-12-01 10:27               ` Lee Jones [this message]
2020-11-28 22:41 ` [PATCH v2 14/28] video: fbdev: pm2fb: Fix kernel-doc warnings Sam Ravnborg
2020-11-30 12:15   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 15/28] video: fbdev: neofb: Fix set but not used warning for CursorMem Sam Ravnborg
2020-11-30 12:16   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 16/28] video: fbdev: hgafb: Fix kernel-doc warnings Sam Ravnborg
2020-11-29 16:10   ` Randy Dunlap
2020-11-28 22:41 ` [PATCH v2 17/28] video: fbdev: tgafb: Fix kernel-doc and set but not used warnings Sam Ravnborg
2020-11-30 13:04   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 18/28] video: fbdev: mx3fb: Fix kernel-doc, set but not used and string warnings Sam Ravnborg
2020-11-30 13:22   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 19/28] video: fbdev: sstfb: Updated logging to fix set but not used warnings Sam Ravnborg
2020-11-30 14:25   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 20/28] video: fbdev: nvidia: Fix " Sam Ravnborg
2020-11-30 14:35   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 21/28] video: fbdev: tmiofb: " Sam Ravnborg
2020-11-30 14:36   ` Thomas Zimmermann
2020-11-30 18:46     ` Sam Ravnborg
2020-11-28 22:41 ` [PATCH v2 22/28] video: fbdev: omapfb: Fix set but not used warnings in dsi Sam Ravnborg
2020-12-01 10:03   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 23/28] video: fbdev: omapfb: Fix set but not used warnings in hdmi*_core Sam Ravnborg
2020-12-01 10:06   ` Thomas Zimmermann
2020-12-05 20:58     ` Sam Ravnborg
2020-11-28 22:41 ` [PATCH v2 24/28] video: fbdev: s3c-fb: Fix kernel-doc and set but not used warnings Sam Ravnborg
2020-12-01 10:07   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 25/28] video: fbdev: uvesafb: Fix set but not used warning Sam Ravnborg
2020-12-01 10:09   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 26/28] video: fbdev: uvesafb: Fix string related warnings Sam Ravnborg
2020-12-01 14:19   ` Thomas Zimmermann
2020-11-28 22:41 ` [PATCH v2 27/28] video: fbdev: cirrusfb: Fix kernel-doc and set but not used warnings Sam Ravnborg
2020-12-01 14:21   ` Thomas Zimmermann
2020-12-05 20:18     ` Sam Ravnborg
2020-11-28 22:41 ` [PATCH v2 28/28] video: fbdev: s1d13xxxfb: " Sam Ravnborg
2020-11-29  9:59   ` Thomas Zimmermann
2020-11-29 21:52     ` Sam Ravnborg
2020-12-01 14:23       ` Thomas Zimmermann

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20201201102704.GH4801@dell \
    --to=lee.jones@linaro.org \
    --cc=FlorianSchandinat@gmx.de \
    --cc=alex.dewar90@gmail.com \
    --cc=arnd@arndb.de \
    --cc=b.zolnierkie@samsung.com \
    --cc=daniel.vetter@ffwll.ch \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=george.kennedy@oracle.com \
    --cc=grandmaster@al2klimov.de \
    --cc=gregkh@linuxfoundation.org \
    --cc=gustavoars@kernel.org \
    --cc=jani.nikula@intel.com \
    --cc=jingoohan1@gmail.com \
    --cc=jirislaby@kernel.org \
    --cc=joe@perches.com \
    --cc=kristoffer.ericson@gmail.com \
    --cc=laurent.pinchart@ideasonboard.com \
    --cc=linux-fbdev@vger.kernel.org \
    --cc=natechancellor@gmail.com \
    --cc=novikov@ispras.ru \
    --cc=pakki001@umn.edu \
    --cc=peda@axentia.se \
    --cc=penguin-kernel@i-love.sakura.ne.jp \
    --cc=rdunlap@infradead.org \
    --cc=rppt@kernel.org \
    --cc=saeed.mirzamohammadi@oracle.com \
    --cc=sam@ravnborg.org \
    --cc=tanxiaofei@huawei.com \
    --cc=thomas@winischhofer.net \
    --cc=tzimmermann@suse.de \
    --cc=vaibhavgupta40@gmail.com \
    --cc=yanaijie@huawei.com \
    --cc=yepeilin.cs@gmail.com \
    --cc=zhangqilong3@huawei.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).