Re: [PATCH 01/12] docs: kdoc; Add a rudimentary class to represent output items

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed,  2 Jul 2025 16:35:13 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> This class is intended to replace the unstructured dict used to accumulate
> an entry to pass to an output module.  For now, it remains unstructured,
> but it works well enough that the output classes don't notice the
> difference.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

> ---
>  scripts/lib/kdoc/kdoc_item.py   | 26 ++++++++++++++++++++++++++
>  scripts/lib/kdoc/kdoc_parser.py | 30 +++++++++---------------------
>  2 files changed, 35 insertions(+), 21 deletions(-)
>  create mode 100644 scripts/lib/kdoc/kdoc_item.py
> 
> diff --git a/scripts/lib/kdoc/kdoc_item.py b/scripts/lib/kdoc/kdoc_item.py
> new file mode 100644
> index 000000000000..add2cc772fec
> --- /dev/null
> +++ b/scripts/lib/kdoc/kdoc_item.py
> @@ -0,0 +1,26 @@
> +# SPDX-License-Identifier: GPL-2.0
> +#
> +# A class that will, eventually, encapsulate all of the parsed data that we
> +# then pass into the output modules.
> +#
> +
> +class KdocItem:
> +    def __init__(self, name, type, start_line, **other_stuff):
> +        self.name = name
> +        self.type = type
> +        self.declaration_start_line = start_line
> +        #
> +        # Just save everything else into our own dict so that the output
> +        # side can grab it directly as before.  As we move things into more
> +        # structured data, this will, hopefully, fade away.
> +        #
> +        self.other_stuff = other_stuff
> +
> +    def get(self, key, default = None):
> +        ret = self.other_stuff.get(key, default)
> +        if ret == default:
> +            return self.__dict__.get(key, default)
> +        return ret
> +
> +    def __getitem__(self, key):
> +        return self.get(key)
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 831f061f61b8..a5a59b97a444 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -16,7 +16,7 @@ import re
>  from pprint import pformat
>  
>  from kdoc_re import NestedMatch, KernRe
> -
> +from kdoc_item import KdocItem
>  
>  #
>  # Regular expressions used to parse kernel-doc markups at KernelDoc class.
> @@ -271,32 +271,20 @@ class KernelDoc:
>          The actual output and output filters will be handled elsewhere
>          """
>  
> -        # The implementation here is different than the original kernel-doc:
> -        # instead of checking for output filters or actually output anything,
> -        # it just stores the declaration content at self.entries, as the
> -        # output will happen on a separate class.
> -        #
> -        # For now, we're keeping the same name of the function just to make
> -        # easier to compare the source code of both scripts
> -
> -        args["declaration_start_line"] = self.entry.declaration_start_line
> -        args["type"] = dtype
> -        args["warnings"] = self.entry.warnings
> -
> -        # TODO: use colletions.OrderedDict to remove sectionlist
> +        item = KdocItem(name, dtype, self.entry.declaration_start_line, **args)
> +        item.warnings = self.entry.warnings
>  
> -        sections = args.get('sections', {})
> -        sectionlist = args.get('sectionlist', [])
> +        sections = item.get('sections', {})
> +        sectionlist = item.get('sectionlist', [])
>  
>          # Drop empty sections
>          # TODO: improve empty sections logic to emit warnings
>          for section in ["Description", "Return"]:
> -            if section in sectionlist:
> -                if not sections[section].rstrip():
> -                    del sections[section]
> -                    sectionlist.remove(section)
> +            if section in sectionlist and not sections[section].rstrip():
> +                del sections[section]
> +                sectionlist.remove(section)
>  
> -        self.entries.append((name, args))
> +        self.entries.append((name, item))
>  
>          self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
>  



Thanks,
Mauro