linux-fbdev.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Daniel Vetter <daniel.vetter@ffwll.ch>
To: Lee Jones <lee.jones@linaro.org>
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 11:04:01 +0100	[thread overview]
Message-ID: <CAKMK7uGUJbVRVTO8xL8Kc8BbYMXzqS2KAVYL8bgex3Zz=aF9EQ@mail.gmail.com> (raw)
In-Reply-To: <20201201094629.GG4801@dell>

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

  reply	other threads:[~2020-12-01 10:05 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 [this message]
2020-12-01 10:27               ` Lee Jones
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='CAKMK7uGUJbVRVTO8xL8Kc8BbYMXzqS2KAVYL8bgex3Zz=aF9EQ@mail.gmail.com' \
    --to=daniel.vetter@ffwll.ch \
    --cc=FlorianSchandinat@gmx.de \
    --cc=alex.dewar90@gmail.com \
    --cc=arnd@arndb.de \
    --cc=b.zolnierkie@samsung.com \
    --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=lee.jones@linaro.org \
    --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).