Skip to contentSkip to conversation

Fix invalid kernel-doc warnings

PATCH In review Pavan Kumar Linga 2 participants 5 messages Aug 15, 2023 – Aug 18, 2023 Documentation

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index d0116c6939dc..cfb1cb223508 100755
@@ -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
#2 lore raw

PATCH v3 2/2 scripts: kernel-doc: fix macro handling in enums

In reply to Pavan Kumar Linga

drivers/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
index cfb1cb223508..6e199a745ccb 100755
@@ -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
maintainer
#3 lore raw
In reply to Pavan Kumar Linga
Quoted 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 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]/
---

Quoted 6 lines

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(+)

Series applied, thanks.

jon

#4 lore raw
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 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

Quoted 6 lines
Quoted 2 lines
  scripts/kernel-doc | 5 +++++
  1 file changed, 5 insertions(+)

Series applied, thanks.

jon

Thanks Jon.

Regards,
Pavan