Fix invalid kernel-doc warnings
Subsystems (3)
v2 cover Fix invalid kernel-doc warnings
kernel-doc reports invalid warnings on IDPF driver patch series [1] that is submitted for review. This patch series fixes those warnings.
[1]: https://lore.kernel.org/netdev/[email protected]/
---
v1 -> v2:
* Fix typos in the commit message
net-next:
v1 - https://lore.kernel.org/netdev/[email protected]/
These fixes are needed for the IDPF driver patch series to have a clean CI. So targeting the series to net-next instead of linux-docs.
---
Pavan Kumar Linga (2):
scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
scripts: kernel-doc: fix macro handling in enums
scripts/kernel-doc | 5 +++++ 1 file changed, 5 insertions(+)
Signature · 1 line
2.38.1
PATCH v2 1/2 scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
At present, if the macros DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN() are used in the structures as shown below, instead of parsing the parameter in the parentheses, kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and 'DEFINE_DMA_UNMAP_LEN(' which results in the following warnings:
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in 'idpf_tx_buf' drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in 'idpf_tx_buf'
struct idpf_tx_buf {
DEFINE_DMA_UNMAP_ADDR(dma);
DEFINE_DMA_UNMAP_LEN(len);
};Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN().
--- scripts/kernel-doc | 4 ++++ 1 file changed, 4 insertions(+)
scripts/kernel-doc +4 -0
@@ -1168,6 +1168,10 @@ sub dump_struct($$) { $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos; # replace DECLARE_FLEX_ARRAY $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos; + #replace DEFINE_DMA_UNMAP_ADDR + $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos; + #replace DEFINE_DMA_UNMAP_LEN + $members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos; my $declaration = $members; # Split nested struct/union elements as newer ones
Signature · 1 line
2.38.1
Jonathan Corbet
maintainerRe: [PATCH net-next v2 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
Quoted 19 lines · Pavan Kumar Linga
At present, if the macros
DEFINE_DMA_UNMAP_ADDR()andDEFINE_DMA_UNMAP_LEN()are used in the structures as shown below, instead of parsing the parameter in the parentheses, kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and 'DEFINE_DMA_UNMAP_LEN(' which results in the following warnings:
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in 'idpf_tx_buf'drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in 'idpf_tx_buf'struct idpf_tx_buf { DEFINE_DMA_UNMAP_ADDR(dma); DEFINE_DMA_UNMAP_LEN(len); };
Quoted 8 lines
Fix the warnings by parsing
DEFINE_DMA_UNMAP_ADDR()andDEFINE_DMA_UNMAP_LEN().Signed-off-by Pavan Kumar Linga <[email protected]>Acked-by Randy Dunlap <[email protected]>--- scripts/kernel-doc | 4 ++++ 1 file changed, 4 insertions(+)
Is there a reason why you didn't CC me on these?
scripts/kernel-doc sub dump_struct($$) { · line 1175
Quoted 13 lines
scripts/kernel-doc +4
-0@@ -1168,6 +1168,10 @@ sub dump_struct($$) { $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos; # replace DECLARE_FLEX_ARRAY $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos; + #replace DEFINE_DMA_UNMAP_ADDR + $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos; + #replace DEFINE_DMA_UNMAP_LEN + $members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos; my $declaration = $members;
I'm not happy with this ... we are continuing to reimplement parts of the C preprocessor here, badly, creating an ugly mess in the process.
That said, you are just the latest arrival at the party, can't blame you for this. Until we come up with a better way here, I guess this will do.
Thanks,
jon
Re: [PATCH net-next v2 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
Quoted 24 lines · Jonathan Corbet
Quoted 22 lines · Pavan Kumar Linga
At present, if the macros
DEFINE_DMA_UNMAP_ADDR()andDEFINE_DMA_UNMAP_LEN()are used in the structures as shown below, instead of parsing the parameter in the parentheses, kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and 'DEFINE_DMA_UNMAP_LEN(' which results in the following warnings:
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in 'idpf_tx_buf'drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in 'idpf_tx_buf'struct idpf_tx_buf { DEFINE_DMA_UNMAP_ADDR(dma); DEFINE_DMA_UNMAP_LEN(len); };Fix the warnings by parsing
DEFINE_DMA_UNMAP_ADDR()andDEFINE_DMA_UNMAP_LEN().
Quoted 8 lines
Quoted 5 lines
Signed-off-by Pavan Kumar Linga <[email protected]>Acked-by Randy Dunlap <[email protected]>--- scripts/kernel-doc | 4 ++++ 1 file changed, 4 insertions(+)Is there a reason why you didn't CC me on these?
It was unintentional and my apologies, as I thought CC'ing you while sending the patches should be good. If the ask is to add the 'Cc:' tag to the patch, will do that in the next revision.
Quoted 17 lines
scripts/kernel-doc sub dump_struct($$) { · line 1175
Quoted 13 lines
scripts/kernel-doc +4
-0@@ -1168,6 +1168,10 @@ sub dump_struct($$) { $members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos; # replace DECLARE_FLEX_ARRAY $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos; + #replace DEFINE_DMA_UNMAP_ADDR + $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos; + #replace DEFINE_DMA_UNMAP_LEN + $members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos; my $declaration = $members;I'm not happy with this ... we are continuing to reimplement parts of the C preprocessor here, badly, creating an ugly mess in the process.
Quoted 4 lines
That said, you are just the latest arrival at the party, can't blame you for this. Until we come up with a better way here, I guess this will do.
Thanks for providing your feedback.
Quoted 3 lines
Thanks,
jon
Regards,
Pavan
PATCH v2 2/2 scripts: kernel-doc: fix macro handling in enums
In reply to Pavan Kumar Lingadrivers/net/ethernet/intel/idpf/idpf.h uses offsetof to initialize the enum enumerators:
enum {
IDPF_BASE_CAPS = -1,
IDPF_CSUM_CAPS = offsetof(struct virtchnl2_get_capabilities,
csum_caps),
IDPF_SEG_CAPS = offsetof(struct virtchnl2_get_capabilities,
seg_caps),
IDPF_RSS_CAPS = offsetof(struct virtchnl2_get_capabilities,
rss_caps),
IDPF_HSPLIT_CAPS = offsetof(struct virtchnl2_get_capabilities,
hsplit_caps),
IDPF_RSC_CAPS = offsetof(struct virtchnl2_get_capabilities,
rsc_caps),
IDPF_OTHER_CAPS = offsetof(struct virtchnl2_get_capabilities,
other_caps),
};
kernel-doc parses the above enumerator with a ',' inside the macro and treats 'csum_caps', 'seg_caps' etc. also as enumerators resulting in the warnings:
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'csum_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'seg_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rss_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'hsplit_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rsc_caps' not described in enum 'idpf_cap_field' drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'other_caps' not described in enum 'idpf_cap_field'
Fix it by removing the macro arguments within the parentheses.
--- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+)
scripts/kernel-doc +1 -0
@@ -1353,6 +1353,7 @@ sub dump_enum($$) { my %_members; $members =~ s/\s+$//; + $members =~ s/\(.*?[\)]//g; foreach my $arg (split ',', $members) { $arg =~ s/^\s*(\w+).*/$1/;
Signature · 1 line
2.38.1
Jonathan Corbet
maintainerRe: [PATCH net-next v2 2/2] scripts: kernel-doc: fix macro handling in enums
Quoted 48 lines · Pavan Kumar Linga
drivers/net/ethernet/intel/idpf/idpf.huses offsetof to initialize the enum enumerators:enum {
IDPF_BASE_CAPS= -1,
IDPF_CSUM_CAPS= offsetof(structvirtchnl2_get_capabilities,
csum_caps),
IDPF_SEG_CAPS= offsetof(structvirtchnl2_get_capabilities,
seg_caps),
IDPF_RSS_CAPS= offsetof(structvirtchnl2_get_capabilities,
rss_caps),
IDPF_HSPLIT_CAPS= offsetof(structvirtchnl2_get_capabilities,
hsplit_caps),
IDPF_RSC_CAPS= offsetof(structvirtchnl2_get_capabilities,
rsc_caps),
IDPF_OTHER_CAPS= offsetof(structvirtchnl2_get_capabilities,
other_caps),
};kernel-doc parses the above enumerator with a ',' inside the macro and treats '
csum_caps', 'seg_caps' etc. also as enumerators resulting in the warnings:
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'csum_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'seg_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rss_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'hsplit_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rsc_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'other_caps' not described in enum 'idpf_cap_field'Fix it by removing the macro arguments within the parentheses.
Signed-off-by Pavan Kumar Linga <[email protected]>--- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+)scripts/kernel-doc +0
-0
scripts/kernel-doc sub dump_enum($$) { · line 1356
Quoted 4 lines
scripts/kernel-doc +1
-0@@ -1353,6 +1353,7 @@ sub dump_enum($$) { my %_members; $members =~ s/\s+$//; + $members =~ s/\(.*?[\)]//g;
".*" matches the empty string, so * think the "?" is unnecessary.
I do worry that this regex could match more than expected, disappearing everything up to a final parenthesis. It doesn't cause any changes in the current docs build, but still ... How do you feel about replacing ".*" with "[^;]*" ?
Thanks,
jon
Re: [PATCH net-next v2 2/2] scripts: kernel-doc: fix macro handling in enums
Quoted 52 lines · Jonathan Corbet
Quoted 50 lines · Pavan Kumar Linga
drivers/net/ethernet/intel/idpf/idpf.huses offsetof to initialize the enum enumerators:enum {
IDPF_BASE_CAPS= -1,
IDPF_CSUM_CAPS= offsetof(structvirtchnl2_get_capabilities,
csum_caps),
IDPF_SEG_CAPS= offsetof(structvirtchnl2_get_capabilities,
seg_caps),
IDPF_RSS_CAPS= offsetof(structvirtchnl2_get_capabilities,
rss_caps),
IDPF_HSPLIT_CAPS= offsetof(structvirtchnl2_get_capabilities,
hsplit_caps),
IDPF_RSC_CAPS= offsetof(structvirtchnl2_get_capabilities,
rsc_caps),
IDPF_OTHER_CAPS= offsetof(structvirtchnl2_get_capabilities,
other_caps),
};kernel-doc parses the above enumerator with a ',' inside the macro and treats '
csum_caps', 'seg_caps' etc. also as enumerators resulting in the warnings:
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'csum_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'seg_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rss_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'hsplit_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'rsc_caps' not described in enum 'idpf_cap_field'drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value 'other_caps' not described in enum 'idpf_cap_field'Fix it by removing the macro arguments within the parentheses.
Signed-off-by Pavan Kumar Linga <[email protected]>--- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+)scripts/kernel-doc +0
-0@@ -1353,6 +1353,7 @@ sub dump_enum($$) { my %_members;
Quoted 5 lines
scripts/kernel-doc sub dump_enum($$) { · line 1356
Quoted 2 lines
scripts/kernel-doc +1
-0$members =~ s/\s+$//; + $members =~ s/\(.*?[\)]//g;".*" matches the empty string, so * think the "?" is unnecessary.
As suggested, tried without "?" in the below updated regex and it doesn't parse right. It substitutes everything from the 1st "(" to the last ")" with empty string whereas using "?" substitutes each "( )" with empty string.
Quoted 5 lines
I do worry that this regex could match more than expected, disappearing everything up to a final parenthesis. It doesn't cause any changes in the current docs build, but still ... How do you feel about replacing ".*" with "[^;]*" ?
Thanks for the suggestion and that works for me. After the update, the regex would look like:
"$members =~ s/\([^;]*?[\)]//g;"
Will update this in the next revision.
Quoted 3 lines
Thanks,
jon
Regards,
Pavan
Quoted 16 lines · Pavan Kumar Linga
kernel-doc reports invalid warnings on IDPF driver patch series [1] that is submitted for review. This patch series fixes those warnings.
[1]: https://lore.kernel.org/netdev/[email protected]/
---
v1 -> v2:
* Fix typos in the commit messagenet-next:
v1 - https://lore.kernel.org/netdev/[email protected]/These fixes are needed for the IDPF driver patch series to have a clean CI. So targeting the series to net-next instead of linux-docs.
---
Quoted 6 lines
Pavan Kumar Linga (2):
scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
scripts: kernel-doc: fix macro handling in enumsscripts/kernel-doc | 5 +++++ 1 file changed, 5 insertions(+)
I have one comment on the second patch, and I'll grumble again about not being copied on these, but I guess the series is OK. I can drop it into docs-next for the merge window. If there is some need to take it via another path, then:
...just let me know.
Thanks,
jon