Fix invalid kernel-doc warnings
v3 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]/
---
v2 -> v3:
* Changed from net-next to docs-next based on Jonathan's comment:
https://lore.kernel.org/netdev/[email protected]/
* Added a 'Cc' tag in the commit message
(patch 2):
* Replaced ".*" with "[^;]*" in the regex
v1 -> v2:
* Fix typos in the commit message
net-next:
v2 - https://lore.kernel.org/netdev/[email protected]/
v1 - https://lore.kernel.org/netdev/[email protected]/
---
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 v3 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
PATCH v3 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_cap_field {
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
maintainerQuoted 20 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]/
---
v2 -> v3:
* Changed from net-next to docs-next based on Jonathan's comment:https://lore.kernel.org/netdev/[email protected]/* Added a 'Cc' tag in the commit message
(patch 2):
* Replaced ".*" with "[^;]*" in the regexv1 -> v2:
* Fix typos in the commit messagenet-next:
v2 - https://lore.kernel.org/netdev/[email protected]/
v1 - https://lore.kernel.org/netdev/[email protected]/
---
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(+)
Series applied, thanks.
jon
Quoted 26 lines · Jonathan Corbet
Quoted 24 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]/
---
v2 -> v3:
* Changed from net-next to docs-next based on Jonathan's comment:https://lore.kernel.org/netdev/[email protected]/* Added a 'Cc' tag in the commit message
(patch 2):
* Replaced ".*" with "[^;]*" in the regexv1 -> v2:
* Fix typos in the commit messagenet-next:
v2 - https://lore.kernel.org/netdev/[email protected]/
v1 - https://lore.kernel.org/netdev/[email protected]/
---Pavan Kumar Linga (2):
scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
scripts: kernel-doc: fix macro handling in enums
Quoted 6 lines
Quoted 2 lines
scripts/kernel-doc | 5 +++++ 1 file changed, 5 insertions(+)Series applied, thanks.
jon
Thanks Jon.
Regards,
Pavan