[PATCH net-next v2 0/2] Fix invalid kernel-doc warnings

[PATCH net-next v2 0/2] Fix invalid kernel-doc warnings

[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/20230808003416.3805142-1-anthony.l.nguyen@intel.com/
---
v1 -> v2:
 * Fix typos in the commit message

net-next:
v1 - https://lore.kernel.org/netdev/20230812002549.36286-1-pavan.kumar.linga@intel.com/

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

-- 
2.38.1

[PATCH net-next v2 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

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

Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
---
 scripts/kernel-doc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d0116c6939dc..cfb1cb223508 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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
-- 
2.38.1

[PATCH net-next v2 2/2] scripts: kernel-doc: fix macro handling in enums

[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.

Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
---
 scripts/kernel-doc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cfb1cb223508..bc008f30f3c9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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/;
-- 
2.38.1

Re: [PATCH net-next v2 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

[Jonathan Corbet]

Pavan Kumar Linga <pavan.kumar.linga@intel.com> writes:

> 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().
>
> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> ---
>  scripts/kernel-doc | 4 ++++
>  1 file changed, 4 insertions(+)

Is there a reason why you didn't CC me on these?

> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index d0116c6939dc..cfb1cb223508 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -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 2/2] scripts: kernel-doc: fix macro handling in enums

[Jonathan Corbet]

Pavan Kumar Linga <pavan.kumar.linga@intel.com> writes:

> 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.
>
> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
> ---
>  scripts/kernel-doc | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index cfb1cb223508..bc008f30f3c9 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -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 0/2] Fix invalid kernel-doc warnings

[Jonathan Corbet]

Pavan Kumar Linga <pavan.kumar.linga@intel.com> writes:

> 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/20230808003416.3805142-1-anthony.l.nguyen@intel.com/
> ---
> v1 -> v2:
>  * Fix typos in the commit message
>
> net-next:
> v1 - https://lore.kernel.org/netdev/20230812002549.36286-1-pavan.kumar.linga@intel.com/
>
> 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(+)

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:

Acked-by: Jonathan Corbet <corbet@lwn.net>

...just let me know.

Thanks,

jon

Re: [PATCH net-next v2 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

[Linga, Pavan Kumar]

On 8/14/2023 11:57 AM, Jonathan Corbet wrote:
> Pavan Kumar Linga <pavan.kumar.linga@intel.com> writes:
> 
>> 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().
>>
>> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
>> Acked-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>>   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.

>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index d0116c6939dc..cfb1cb223508 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -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 for providing your feedback.

> Thanks,
> 
> jon

Regards,
Pavan

Re: [PATCH net-next v2 2/2] scripts: kernel-doc: fix macro handling in enums

[Linga, Pavan Kumar]

On 8/14/2023 11:59 AM, Jonathan Corbet wrote:
> Pavan Kumar Linga <pavan.kumar.linga@intel.com> writes:
> 
>> 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.
>>
>> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
>> ---
>>   scripts/kernel-doc | 1 +
>>   1 file changed, 1 insertion(+)
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index cfb1cb223508..bc008f30f3c9 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -1353,6 +1353,7 @@ sub dump_enum($$) {
>>   	my %_members;
>>   
>>   	$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.

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

> Thanks,
> 
> jon

Regards,
Pavan