On 8/14/2023 11:59 AM, Jonathan Corbet wrote:

Pavan Kumar Linga [off-list ref] writes:

quoted

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