* [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc
@ 2024-03-26 17:38 Donald Hunter
2024-03-26 18:04 ` Randy Dunlap
2024-03-29 14:50 ` Jonathan Corbet
0 siblings, 2 replies; 4+ messages in thread
From: Donald Hunter @ 2024-03-26 17:38 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc; +Cc: donald.hunter, Donald Hunter
kernel-doc doesn't handle bitfields that are specified with symbolic
name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX
This results in the following warnings when running `make htmldocs`:
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'
Update the regexp for bitfields to accept all word chars, not just
digits.
Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
---
scripts/kernel-doc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 967f1abb0edb..cb1be22afc65 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1541,7 +1541,7 @@ sub create_parameterlist($$$$) {
save_struct_actual($2);
push_parameter($2, "$type $1", $arg, $file, $declaration_name);
- } elsif ($param =~ m/(.*?):(\d+)/) {
+ } elsif ($param =~ m/(.*?):(\w+)/) {
if ($type ne "") { # skip unnamed bit-fields
save_struct_actual($1);
push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
--
2.44.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc
2024-03-26 17:38 [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc Donald Hunter
@ 2024-03-26 18:04 ` Randy Dunlap
2024-03-29 14:50 ` Jonathan Corbet
1 sibling, 0 replies; 4+ messages in thread
From: Randy Dunlap @ 2024-03-26 18:04 UTC (permalink / raw)
To: Donald Hunter, Jonathan Corbet, linux-doc; +Cc: donald.hunter
On 3/26/24 10:38, Donald Hunter wrote:
> kernel-doc doesn't handle bitfields that are specified with symbolic
> name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX
>
> This results in the following warnings when running `make htmldocs`:
>
> 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'
>
> Update the regexp for bitfields to accept all word chars, not just
> digits.
>
> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.
That takes care of item #2 on my kernel-doc issues list:
https://lore.kernel.org/linux-doc/3a6a7dd0-72f1-44c6-b0bc-b1ce76fca76a@infradead.org/
> ---
> scripts/kernel-doc | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 967f1abb0edb..cb1be22afc65 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1541,7 +1541,7 @@ sub create_parameterlist($$$$) {
> save_struct_actual($2);
>
> push_parameter($2, "$type $1", $arg, $file, $declaration_name);
> - } elsif ($param =~ m/(.*?):(\d+)/) {
> + } elsif ($param =~ m/(.*?):(\w+)/) {
> if ($type ne "") { # skip unnamed bit-fields
> save_struct_actual($1);
> push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
--
#Randy
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc
2024-03-26 17:38 [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc Donald Hunter
2024-03-26 18:04 ` Randy Dunlap
@ 2024-03-29 14:50 ` Jonathan Corbet
2024-03-29 15:59 ` Randy Dunlap
1 sibling, 1 reply; 4+ messages in thread
From: Jonathan Corbet @ 2024-03-29 14:50 UTC (permalink / raw)
To: Donald Hunter, linux-doc; +Cc: donald.hunter, Donald Hunter
Donald Hunter <donald.hunter@gmail.com> writes:
> kernel-doc doesn't handle bitfields that are specified with symbolic
> name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX
>
> This results in the following warnings when running `make htmldocs`:
>
> 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'
>
> Update the regexp for bitfields to accept all word chars, not just
> digits.
>
> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
> ---
> scripts/kernel-doc | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index 967f1abb0edb..cb1be22afc65 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1541,7 +1541,7 @@ sub create_parameterlist($$$$) {
> save_struct_actual($2);
>
> push_parameter($2, "$type $1", $arg, $file, $declaration_name);
> - } elsif ($param =~ m/(.*?):(\d+)/) {
> + } elsif ($param =~ m/(.*?):(\w+)/) {
> if ($type ne "") { # skip unnamed bit-fields
This patch changes this warning:
./include/linux/spi/spi.h:778: warning: Function parameter or struct member 'last_cs_index_mask:SPI_CS_CNT_MAX' not described in 'spi_controller'
to:
./include/linux/spi/spi.h:778: warning: Function parameter or struct member 'last_cs_index_mask' not described in 'spi_controller'
We might get a grumble from Stephen on that, but so be it, it's a step
in the right direction, anyway.
Applied, thanks.
jon
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc
2024-03-29 14:50 ` Jonathan Corbet
@ 2024-03-29 15:59 ` Randy Dunlap
0 siblings, 0 replies; 4+ messages in thread
From: Randy Dunlap @ 2024-03-29 15:59 UTC (permalink / raw)
To: Jonathan Corbet, Donald Hunter, linux-doc; +Cc: donald.hunter
On 3/29/24 07:50, Jonathan Corbet wrote:
> Donald Hunter <donald.hunter@gmail.com> writes:
>
>> kernel-doc doesn't handle bitfields that are specified with symbolic
>> name, e.g. u32 cs_index_mask : SPI_CS_CNT_MAX
>>
>> This results in the following warnings when running `make htmldocs`:
>>
>> 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'
>>
>> Update the regexp for bitfields to accept all word chars, not just
>> digits.
>>
>> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
>> ---
>> scripts/kernel-doc | 2 +-
>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index 967f1abb0edb..cb1be22afc65 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -1541,7 +1541,7 @@ sub create_parameterlist($$$$) {
>> save_struct_actual($2);
>>
>> push_parameter($2, "$type $1", $arg, $file, $declaration_name);
>> - } elsif ($param =~ m/(.*?):(\d+)/) {
>> + } elsif ($param =~ m/(.*?):(\w+)/) {
>> if ($type ne "") { # skip unnamed bit-fields
>
> This patch changes this warning:
>
> ./include/linux/spi/spi.h:778: warning: Function parameter or struct member 'last_cs_index_mask:SPI_CS_CNT_MAX' not described in 'spi_controller'
>
> to:
>
> ./include/linux/spi/spi.h:778: warning: Function parameter or struct member 'last_cs_index_mask' not described in 'spi_controller'
>
> We might get a grumble from Stephen on that, but so be it, it's a step
> in the right direction, anyway.
I have submitted a patch for that one (new warning).
--
#Randy
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2024-03-29 15:59 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-03-26 17:38 [PATCH docs-next v1] docs: Fix bitfield handling in kernel-doc Donald Hunter
2024-03-26 18:04 ` Randy Dunlap
2024-03-29 14:50 ` Jonathan Corbet
2024-03-29 15:59 ` Randy Dunlap
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.