[PATCH docs-next v3 0/2] Fix invalid kernel-doc warnings

[PATCH docs-next v3 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/
---
v2 -> v3:
 * Changed from net-next to docs-next based on Jonathan's comment:
   https://lore.kernel.org/netdev/87pm3pv47i.fsf@meer.lwn.net/
 * 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/20230814170720.46229-1-pavan.kumar.linga@intel.com/
v1 - https://lore.kernel.org/netdev/20230812002549.36286-1-pavan.kumar.linga@intel.com/
---

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 docs-next v3 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().

Cc: Jonathan Corbet <corbet@lwn.net>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
---
 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 docs-next v3 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_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.

Cc: Jonathan Corbet <corbet@lwn.net>
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..6e199a745ccb 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 docs-next v3 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/
> ---
> v2 -> v3:
>  * Changed from net-next to docs-next based on Jonathan's comment:
>    https://lore.kernel.org/netdev/87pm3pv47i.fsf@meer.lwn.net/
>  * 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/20230814170720.46229-1-pavan.kumar.linga@intel.com/
> v1 - https://lore.kernel.org/netdev/20230812002549.36286-1-pavan.kumar.linga@intel.com/
> ---
>
> 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

Re: [PATCH docs-next v3 0/2] Fix invalid kernel-doc warnings

[Linga, Pavan Kumar]

On 8/18/2023 10:24 AM, Jonathan Corbet wrote:
> 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/
>> ---
>> v2 -> v3:
>>   * Changed from net-next to docs-next based on Jonathan's comment:
>>     https://lore.kernel.org/netdev/87pm3pv47i.fsf@meer.lwn.net/
>>   * 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/20230814170720.46229-1-pavan.kumar.linga@intel.com/
>> v1 - https://lore.kernel.org/netdev/20230812002549.36286-1-pavan.kumar.linga@intel.com/
>> ---
>>
>> 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

Thanks Jon.

Regards,
Pavan