From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Matthew Wilcox <willy@infradead.org>
Cc: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names
Date: Thu, 5 Nov 2020 16:20:59 +0100 [thread overview]
Message-ID: <20201105162059.366b44bc@coco.lan> (raw)
In-Reply-To: <20201105150017.GL17076@casper.infradead.org>
Em Thu, 5 Nov 2020 15:00:17 +0000
Matthew Wilcox <willy@infradead.org> escreveu:
> On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote:
> > Kernel-doc currently expects that the kernel-doc markup to come
> > just before the function/enum/struct/union/typedef prototype.
> >
> > Yet, if it find things like:
> >
> > /**
> > * refcount_add - add a value to a refcount
> > * @i: the value to add to the refcount
> > * @r: the refcount
> > */
> > static inline void __refcount_add(int i, refcount_t *r, int *oldp);
> > static inline void refcount_add(int i, refcount_t *r);
> >
> > Kernel-doc will do the wrong thing:
>
> I wonder if we could change kernel-doc to be (optionally) less verbose.
> If we allowed people to write:
>
> /**
> * Add a value to a refcount.
> * @i: The value to add to the refcount
> * @r: The refcount
> */
>
> and had the kernel-doc script pick up the name of the following function
> automatically, would that be an improvement we could all agree on?
Matthew,
As patches are usually generated with -U3, the context lines are
not enough to show if a comment preceding a function is a kernel-doc
markup or a normal comment.
In practice, on some patches at this series, I found real issues
because something else was added between the kernel-doc markup
and the documented function.
So, for me, it sounds a bad idea to remove the function name, as
this can be used to detect such issues.
Thanks,
Mauro
next prev parent reply other threads:[~2020-11-05 15:21 UTC|newest]
Thread overview: 162+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-23 16:32 [PATCH v3 00/56] Fix several bad kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 01/56] scripts: kernel-doc: fix typedef parsing Mauro Carvalho Chehab
2020-10-23 17:22 ` Jonathan Corbet
2020-10-23 18:01 ` Joe Perches
2020-10-26 7:03 ` Mauro Carvalho Chehab
2020-10-27 3:55 ` Joe Perches
2020-10-27 8:37 ` Mauro Carvalho Chehab
2020-10-24 6:43 ` Mauro Carvalho Chehab
2020-10-26 5:55 ` Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 02/56] drm: amdgpu_dm: fix a typo Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 19:02 ` Alex Deucher
2020-10-23 19:02 ` Alex Deucher
2020-10-23 19:02 ` Alex Deucher
2020-10-23 16:32 ` [PATCH v3 03/56] amdgpu: fix a few kernel-doc markup issues Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:38 ` Christian König
2020-10-23 16:38 ` Christian König
2020-10-23 16:38 ` Christian König
2020-10-23 18:58 ` Alex Deucher
2020-10-23 18:58 ` Alex Deucher
2020-10-23 18:58 ` Alex Deucher
2020-10-23 16:32 ` [PATCH v3 04/56] drm: drm_print.h: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 05/56] s390: " Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 06/56] x86: mtrr: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 07/56] block: blk-mq: " Mauro Carvalho Chehab
2020-10-23 18:20 ` Jens Axboe
2020-10-23 16:32 ` [PATCH v3 08/56] ata: fix some kernel-doc markups Mauro Carvalho Chehab
2020-10-23 18:21 ` Jens Axboe
2020-10-23 16:32 ` [PATCH v3 09/56] drivers: base: " Mauro Carvalho Chehab
2020-10-23 16:32 ` [PATCH v3 10/56] EDAC: " Mauro Carvalho Chehab
2020-11-02 19:37 ` Borislav Petkov
2020-10-23 16:32 ` [PATCH v3 11/56] drm/amdgpu: " Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:50 ` Christian König
2020-10-23 16:50 ` Christian König
2020-10-23 16:50 ` Christian König
2020-10-23 18:59 ` Alex Deucher
2020-10-23 18:59 ` Alex Deucher
2020-10-23 18:59 ` Alex Deucher
2020-10-23 16:32 ` [PATCH v3 12/56] drm: " Mauro Carvalho Chehab
2020-10-23 16:32 ` [Intel-gfx] " Mauro Carvalho Chehab
2020-10-23 16:32 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 13/56] HSI: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 14/56] IB: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-24 21:50 ` Max Gurtovoy
2020-10-24 21:50 ` Max Gurtovoy
2020-10-23 16:33 ` [PATCH v3 15/56] media: " Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-23 17:27 ` Sakari Ailus
2020-10-23 17:27 ` Sakari Ailus
2020-10-23 16:33 ` [PATCH v3 16/56] mei: bus: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 17/56] mtd: rawnand: " Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-30 17:27 ` Miquel Raynal
2020-10-30 17:27 ` Miquel Raynal
2020-10-23 16:33 ` [PATCH v3 18/56] net: phy: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 21:04 ` Andrew Lunn
2020-10-23 16:33 ` [PATCH v3 19/56] net: datagram: fix some " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 20/56] net: core: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 21/56] mac80211: fix " Mauro Carvalho Chehab
2020-10-27 7:26 ` Johannes Berg
2020-10-27 8:00 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 22/56] parport: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 23/56] PCI: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 17:43 ` Bjorn Helgaas
2020-10-24 7:30 ` Mauro Carvalho Chehab
2020-11-05 14:44 ` Bjorn Helgaas
2020-10-23 16:33 ` [PATCH v3 24/56] PNP: " Mauro Carvalho Chehab
2020-10-27 18:24 ` Rafael J. Wysocki
2020-10-23 16:33 ` [PATCH v3 25/56] rapidio: fix kernel-doc a markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 26/56] regulator: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 27/56] scsi: fix some kernel-doc markups Mauro Carvalho Chehab
2020-10-27 1:54 ` Martin K. Petersen
2020-10-23 16:33 ` [PATCH v3 28/56] slimbus: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-26 14:52 ` Srinivas Kandagatla
2020-10-26 14:52 ` Srinivas Kandagatla
2020-10-23 16:33 ` [PATCH v3 29/56] spi: fix a typo inside " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 30/56] uio: fix some kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 31/56] usb: dwc3: fix " Mauro Carvalho Chehab
2020-10-27 6:58 ` Felipe Balbi
2020-10-28 9:08 ` Greg Kroah-Hartman
2020-10-28 9:13 ` Felipe Balbi
2020-10-23 16:33 ` [PATCH v3 32/56] video: fix some " Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 33/56] vme: fix two " Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 34/56] fs: fix " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 35/56] jbd2: " Mauro Carvalho Chehab
2020-10-23 16:57 ` Jan Kara
2020-10-23 16:33 ` [PATCH v3 36/56] locks: fix a typo at a kernel-doc markup Mauro Carvalho Chehab
2020-10-26 12:01 ` Jeff Layton
2020-10-23 16:33 ` [PATCH v3 37/56] pstore/zone: fix " Mauro Carvalho Chehab
2020-10-23 17:40 ` Kees Cook
2020-10-23 16:33 ` [PATCH v3 38/56] clk: " Mauro Carvalho Chehab
2020-11-05 2:01 ` Stephen Boyd
2020-10-23 16:33 ` [PATCH v3 39/56] completion: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 40/56] firmware: stratix10-svc: " Mauro Carvalho Chehab
2020-10-27 17:31 ` Richard Gong
2020-10-23 16:33 ` [PATCH v3 41/56] connector: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 42/56] lib/crc7: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 43/56] hrtimer: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 44/56] genirq: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 45/56] iio: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-29 15:43 ` Jonathan Cameron
2020-10-23 16:33 ` [PATCH v3 46/56] list: fix a typo at the " Mauro Carvalho Chehab
2020-10-23 17:55 ` Andy Shevchenko
2020-10-23 20:50 ` Paul E. McKenney
2020-10-23 16:33 ` [PATCH v3 47/56] memblock: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-25 6:34 ` Mike Rapoport
2020-10-23 16:33 ` [PATCH v3 48/56] sound: " Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-23 18:26 ` Mark Brown
2020-10-23 18:26 ` Mark Brown
2020-10-26 13:46 ` Takashi Iwai
2020-10-26 13:46 ` Takashi Iwai
2020-10-26 14:14 ` Mauro Carvalho Chehab
2020-10-26 14:14 ` Mauro Carvalho Chehab
2020-10-26 14:25 ` Takashi Iwai
2020-10-26 14:25 ` Takashi Iwai
2020-10-23 16:33 ` [PATCH v3 49/56] refcount.h: fix a kernel-doc markup Mauro Carvalho Chehab
2020-10-23 17:40 ` Kees Cook
2020-10-23 19:39 ` Peter Zijlstra
2020-10-23 19:47 ` Jonathan Corbet
2020-10-24 6:28 ` Mauro Carvalho Chehab
2020-10-26 8:10 ` Peter Zijlstra
2020-10-26 9:16 ` Mauro Carvalho Chehab
2020-10-26 9:38 ` Peter Zijlstra
2020-10-23 16:33 ` [PATCH v3 50/56] w1: " Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 51/56] audit: " Mauro Carvalho Chehab
2020-10-23 16:33 ` Mauro Carvalho Chehab
2020-10-25 22:10 ` Paul Moore
2020-10-25 22:10 ` Paul Moore
2020-10-25 22:38 ` Mauro Carvalho Chehab
2020-10-25 22:38 ` Mauro Carvalho Chehab
2020-10-28 0:59 ` Paul Moore
2020-10-28 0:59 ` Paul Moore
2020-10-23 16:33 ` [PATCH v3 52/56] resource: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 53/56] shed: fix kernel-doc markup Mauro Carvalho Chehab
2020-10-23 17:53 ` Steven Rostedt
2020-10-26 10:07 ` Mauro Carvalho Chehab
2020-10-23 16:33 ` [PATCH v3 54/56] mm: fix kernel-doc markups Mauro Carvalho Chehab
2020-10-23 17:46 ` Matthew Wilcox
2020-10-23 16:33 ` [PATCH v3 55/56] selftests: kselftest_harness.h: partially " Mauro Carvalho Chehab
2020-10-23 17:39 ` Kees Cook
2020-10-23 16:33 ` [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names Mauro Carvalho Chehab
2020-10-23 20:02 ` kernel test robot
2020-10-23 20:02 ` kernel test robot
2020-10-23 20:34 ` kernel test robot
2020-10-23 20:34 ` kernel test robot
2020-11-05 15:00 ` Matthew Wilcox
2020-11-05 15:15 ` Jonathan Corbet
2020-11-05 15:30 ` Matthew Wilcox
2020-11-05 15:20 ` Mauro Carvalho Chehab [this message]
2020-10-23 18:12 ` [PATCH v3 00/56] Fix several bad kernel-doc markups Jakub Kicinski
2020-10-23 18:22 ` Mark Brown
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=20201105162059.366b44bc@coco.lan \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=willy@infradead.org \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.