Re: [PATCH 10/12] docs: kdoc: further rewrite_struct_members() cleanup

[Jonathan Corbet <corbet@lwn.net>]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Em Thu, 31 Jul 2025 18:13:24 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> Get rid of some single-use variables and redundant checks, and generally
>> tighten up the code; no logical change.
>> 
>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>> ---
>>  scripts/lib/kdoc/kdoc_parser.py | 89 ++++++++++++++++-----------------
>>  1 file changed, 42 insertions(+), 47 deletions(-)
>> 
>> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
>> index 20e0a2abe13b..2b7d7e646367 100644
>> --- a/scripts/lib/kdoc/kdoc_parser.py
>> +++ b/scripts/lib/kdoc/kdoc_parser.py
>> @@ -673,73 +673,68 @@ class KernelDoc:
>>          while tuples:
>>              for t in tuples:
>>                  newmember = ""
>> -                maintype = t[0]
>> -                s_ids = t[5]
>> -                content = t[3]
>
> The reason I opted for this particular approach...
>> -
>> -                oldmember = "".join(t)
>> -
>> -                for s_id in s_ids.split(','):
>> +                oldmember = "".join(t) # Reconstruct the original formatting
>> +                #
>> +                # Pass through each field name, normalizing the form and formatting.
>> +                #
>> +                for s_id in t[5].split(','):
>
> ... is that it is easier to understand and to maintain:
>
> 	for s_id in s_ids.split(','):
>
> than when magic numbers like this are used:
>
> 	for s_id in t[5].split(','):

Coming into this code, I had a different experience, and found the
variables to just be a layer of indirection I had to pass through to get
to the capture groups and see what was really going on.  That was part
of why I put the group numbers in the comments next to that gnarly
regex, to make that mapping more direct and easier to understand.

I will not insist on this change either - at least not indefinitely :)
I do feel, though, that adding a step between the regex and its use just
serves to obscure things.

(And yes, I don't really think that named groups make things better.
I've found those useful in situations where multiple regexes are in use
and the ordering of the groups may vary, but otherwise have generally
avoided them).

Thanks,

jon