Em Wed, 2 Jul 2025 16:35:13 -0600
Jonathan Corbet <corbet@xxxxxxx> 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@xxxxxxx>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
> 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
