From: Randy Dunlap <rdunlap@infradead.org>
To: Jonathan Corbet <corbet@lwn.net>,
Sakari Ailus <sakari.ailus@linux.intel.com>
Cc: linux-doc@vger.kernel.org, Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: scripts/kernel-doc parsing issues
Date: Mon, 5 Feb 2024 19:50:38 -0800 [thread overview]
Message-ID: <3a6a7dd0-72f1-44c6-b0bc-b1ce76fca76a@infradead.org> (raw)
In-Reply-To: <874jemtq2f.fsf@meer.lwn.net>
[reduced Cc: list]
[was: Re: [PATCH 1/1] kernel-doc: Support arrays of pointers struct fields]
On 2/5/24 16:05, Jonathan Corbet wrote:
> Sakari Ailus <sakari.ailus@linux.intel.com> writes:
>
>>> Sigh ... seeing more indecipherable regexes added to kernel-doc is like
>>> seeing another load of plastic bags dumped into the ocean... it doesn't
>>> change the basic situation, but it's still sad.
>>>
>>> Oh well, applied, thanks.
>>
>> Thanks. I have to say I feel the same...
>>
>> Regexes aren't great for parsing C, that's for sure. :-I But what are the
>> options? Write a proper parser for (a subset of) C?
>
> Every now and then I've pondered on this a bit. There are parsers out
> there, of course; we could consider using something like tree-sitter.
> There's just two little problems:
>
> - That's a massive dependency to drag into the docs build that seems
> unlikely to speed things up.
>
> - kernel-doc is really two parsers - one for C code, one for the
> comment syntax. Strangely, nobody has written a grammar for this
> combination.
>
> A suitably motivated developer could probably create a C+kerneldoc
> grammer that would let us make a rock-solid, tree-sitter-based parser
> that would be mostly maintained by somebody else. But that doesn't get
> us around the "adding a big dependency" problem.
>
> <back to work now...>
As I said here on the RFC patch from Sakari:
https://lore.kernel.org/all/aa94772b-7010-4bba-b099-d3b8fe1b97aa@infradead.org/
"Yet another kernel-doc bug. I have a list of 5 or 6 or 8 bugs that are
similar to this one, but I didn't have this one."
The patch to report Excess struct or union members has unearthed several
kernel-doc "parsing" problems.
I have not tried to fix any of these in scripts/kernel-doc yet. I might get
around to it, but it's not a high priority for me.
Examples:
1) drivers/slimbus/stream.c:49: warning: Excess struct member 'segdist_codes' description in 'segdist_code'
struct declaration and definition together. Also possible that the leading "static const"
confuses scripts/kernel-doc.
2) include/linux/spi/spi.h:246: warning: Function parameter or struct member 'cs_index_mask:SPI_CS_CNT_MAX' not described in 'spi_device'
include/linux/spi/spi.h:246: warning: Excess struct member 'cs_index_mask' description in 'spi_device'
scripts/kernel-doc handles some bit fields in structs successfully, so something is
different about this one.
3) fs/ntfs/compress.c:24: warning: cannot understand function prototype: 'typedef enum '
fs/ntfs/* has been removed in linux-next (still in mainline for a little while), but this
shows that scripts/kernel-doc does not handle a 'typedef enum' successfully.
4) drivers/misc/vmw_balloon.c:260: warning: Excess struct member 'reserved' description in 'vmballoon_batch_entry'
This may be the same problem as #2, with using bit fields in a struct.
5) drivers/base/power/runtime.c:362: warning: Excess function parameter 'dev' description in '__rpm_callback'
Confused by either the first function parameter (a function pointer) or the trailing
__releases() and __acquires() attributes.
6) drivers/md/bcache/request.c:309: warning: expecting prototype for bch_data_insert(). Prototype was for CLOSURE_CALLBACK() instead
and
fs/bcachefs/io_write.c:1558: warning: expecting prototype for bch2_write(). Prototype was for CLOSURE_CALLBACK() instead
CLOSURE_CALLBACK() and function parameters are confusing scripts/kernel-doc.
7) drivers/iio/adc/at91-sama5d2_adc.c:471: warning: Excess struct member 'adc_channels' description in 'at91_adc_platform'
Fixed by Sakari's patch. :)
8) drivers/pci/controller/pcie-iproc-msi.c:110: warning: Excess struct member 'reg_offsets' description in 'iproc_msi'
Fixed by Sakari's patch. :)
9) drivers/usb/gadget/udc/pch_udc.c:361: warning: Excess struct member 'stall' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'prot_stall' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'registered' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'suspended' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'connected' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'vbus_session' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'set_cfg_not_acked' description in 'pch_udc_dev'
pch_udc.c:361: warning: Excess struct member 'waiting_zlp_ack' description in 'pch_udc_dev'
All of these except @registered (which is just an Excess description) are declared with one
'unsigned' followed by a list of bit fields, which isn't kernel coding style but it is valid C.
or it might just be 'unsigned' without having a following 'int' that is the problem. I don't
know -- haven't looked yet.
10) Matthew Wilcox pointed out to me that commit 0d55d48b19ff is causing problems with
generated output. A few instances of using TAB or multiple spaces have been patched
recently, but there are others that are not being addressed. I don't have a list of these.
I don't know anything about tree-sitter, so if I were going to add a parser, I would
probably (foolishly?) first try using sparse and a sparse extension.
cheers.
--
#Randy
next prev parent reply other threads:[~2024-02-06 3:50 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-31 8:49 [PATCH 1/1] kernel-doc: Support arrays of pointers struct fields Sakari Ailus
2024-02-05 17:04 ` Jonathan Corbet
2024-02-05 21:30 ` Sakari Ailus
2024-02-06 0:05 ` Jonathan Corbet
2024-02-06 3:50 ` Randy Dunlap [this message]
2025-02-14 3:15 ` scripts/kernel-doc parsing issues Randy Dunlap
2025-02-14 7:57 ` Mauro Carvalho Chehab
2024-02-06 11:20 ` [PATCH 1/1] kernel-doc: Support arrays of pointers struct fields Jani Nikula
2024-02-06 15:13 ` Jonathan Corbet
2025-02-14 7:45 ` Mauro Carvalho Chehab
2025-02-14 15:56 ` Jonathan Corbet
2025-02-14 16:29 ` Jani Nikula
2025-02-14 16:38 ` Jonathan Corbet
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=3a6a7dd0-72f1-44c6-b0bc-b1ce76fca76a@infradead.org \
--to=rdunlap@infradead.org \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=mchehab@kernel.org \
--cc=sakari.ailus@linux.intel.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 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.