RE: [PATCH v2 29/28] docs: kdoc: ensure that comments are dropped before calling split_struct_proto()

[Loktionov, Aleksandr]

> -----Original Message-----
> From: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> Sent: Friday, March 13, 2026 9:34 AM
> To: Jonathan Corbet <corbet@xxxxxxx>; Linux Doc Mailing List <linux-
> doc@xxxxxxxxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>; linux-
> kernel@xxxxxxxxxxxxxxx; Loktionov, Aleksandr
> <aleksandr.loktionov@xxxxxxxxx>; Mauro Carvalho Chehab
> <mchehab@xxxxxxxxxx>; Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Subject: [PATCH v2 29/28] docs: kdoc: ensure that comments are dropped
> before calling split_struct_proto()
> 
> Changeset 2b957decdb6c ("docs: kdoc: don't add broken comments inside
> prototypes") revealed a hidden bug at split_struct_proto(): some
> comments there may break its capability of properly identifying a
> struct.
> 
> Fixing it is as simple as stripping comments before calling it.
> 
> Fixes: 2b957decdb6c ("docs: kdoc: don't add broken comments inside
> prototypes")
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py
> b/tools/lib/python/kdoc/kdoc_parser.py
> index 3ff17b07c1c9..ed378edb1e05 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -724,6 +724,7 @@ class KernelDoc:
>          #
>          # Do the basic parse to get the pieces of the declaration.
>          #
> +        proto = trim_private_members(proto)
>          struct_parts = self.split_struct_proto(proto)
>          if not struct_parts:
>              self.emit_msg(ln, f"{proto} error: Cannot parse struct or
> union!") @@ -764,6 +765,7 @@ class KernelDoc:
>          # Strip preprocessor directives.  Note that this depends on
> the
>          # trailing semicolon we added in process_proto_type().
>          #
> +        proto = trim_private_members(proto)
>          proto = KernRe(r'#\s*((define|ifdef|if)\s+|endif)[^;]*;',
> flags=re.S).sub('', proto)
>          #
>          # Parse out the name and members of the enum.  Typedef form
> first.
> @@ -771,7 +773,7 @@ class KernelDoc:
>          r = KernRe(r'typedef\s+enum\s*\{(.*)\}\s*(\w*)\s*;')
>          if r.search(proto):
>              declaration_name = r.group(2)
> -            members = trim_private_members(r.group(1))
> +            members = r.group(1)
>          #
>          # Failing that, look for a straight enum
>          #
> @@ -779,7 +781,7 @@ class KernelDoc:
>              r = KernRe(r'enum\s+(\w*)\s*\{(.*)\}')
>              if r.match(proto):
>                  declaration_name = r.group(1)
> -                members = trim_private_members(r.group(2))
> +                members = r.group(2)
>          #
>          # OK, this isn't going to work.
>          #
> --
> 2.53.0

Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@xxxxxxxxx>