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

["Linga, Pavan Kumar" <pavan.kumar.linga@intel.com>]

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