Skip to contentSkip to conversation

Fix invalid kernel-doc warnings

PATCH Superseded Pavan Kumar Linga 2 participants 8 messages Aug 14, 2023 – Aug 15, 2023

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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

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
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
maintainer
#2 lore raw

Re: [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() 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);
};
Quoted 8 lines

Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and DEFINE_DMA_UNMAP_LEN().

---
 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
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;

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

#3 lore raw

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

Quoted 8 lines
Quoted 5 lines
---
  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
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;

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

#4 lore raw

PATCH v2 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_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..bc008f30f3c9 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
#5 lore raw

Re: [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.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 +0 -0
index cfb1cb223508..bc008f30f3c9 100755

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

#6 lore raw

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.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 +0 -0
index cfb1cb223508..bc008f30f3c9 100755
@@ -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

maintainer Acked-by on the v2 series
#7 lore raw
In reply to Pavan Kumar Linga
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 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.
---

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

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