Re: [PATCH 11/12] docs: kdoc: clean up check_sections()

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

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

> entry.sectcheck is just a duplicate of our list of sections that is only
> passed to check_sections(); its main purpose seems to be to avoid checking
> the special named sections.  Rework check_sections() to not use that field
> (which is then deleted), tocheck for the known sections directly, and
> tighten up the logic in general.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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

> ---
>  scripts/lib/kdoc/kdoc_parser.py | 31 +++++++++++--------------------
>  1 file changed, 11 insertions(+), 20 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 7191fa94e17a..fdde14b045fe 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -42,9 +42,11 @@ doc_decl = doc_com + KernRe(r'(\w+)', cache=False)
>  #         @{section-name}:
>  # while trying to not match literal block starts like "example::"
>  #
> +known_section_names = 'description|context|returns?|notes?|examples?'
> +known_sections = KernRe(known_section_names, flags = re.I)
>  doc_sect = doc_com + \
> -            KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$',
> -                flags=re.I, cache=False)
> +    KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
> +           flags=re.I, cache=False)
>  
>  doc_content = doc_com_body + KernRe(r'(.*)', cache=False)
>  doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False)
> @@ -115,7 +117,6 @@ class KernelEntry:
>          self.config = config
>  
>          self._contents = []
> -        self.sectcheck = ""
>          self.prototype = ""
>  
>          self.warnings = []
> @@ -187,7 +188,6 @@ class KernelEntry:
>              self.parameterdescs[name] = contents
>              self.parameterdesc_start_lines[name] = self.new_start_line
>  
> -            self.sectcheck += name + " "
>              self.new_start_line = 0
>  
>          else:
> @@ -478,29 +478,20 @@ class KernelDoc:
>                          self.push_parameter(ln, decl_type, param, dtype,
>                                              arg, declaration_name)
>  
> -    def check_sections(self, ln, decl_name, decl_type, sectcheck):
> +    def check_sections(self, ln, decl_name, decl_type):
>          """
>          Check for errors inside sections, emitting warnings if not found
>          parameters are described.
>          """
> -
> -        sects = sectcheck.split()
> -
> -        for sx in range(len(sects)):                  # pylint: disable=C0200
> -            err = True
> -            for param in self.entry.parameterlist:
> -                if param == sects[sx]:
> -                    err = False
> -                    break
> -
> -            if err:
> +        for section in self.entry.sections:
> +            if section not in self.entry.parameterlist and \
> +               not known_sections.search(section):
>                  if decl_type == 'function':
>                      dname = f"{decl_type} parameter"
>                  else:
>                      dname = f"{decl_type} member"
> -
>                  self.emit_msg(ln,
> -                              f"Excess {dname} '{sects[sx]}' description in '{decl_name}'")
> +                              f"Excess {dname} '{section}' description in '{decl_name}'")
>  
>      def check_return_section(self, ln, declaration_name, return_type):
>          """
> @@ -754,7 +745,7 @@ class KernelDoc:
>  
>          self.create_parameter_list(ln, decl_type, members, ';',
>                                     declaration_name)
> -        self.check_sections(ln, declaration_name, decl_type, self.entry.sectcheck)
> +        self.check_sections(ln, declaration_name, decl_type)
>  
>          # Adjust declaration for better display
>          declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration)
> @@ -1018,7 +1009,7 @@ class KernelDoc:
>                            f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instead")
>              return
>  
> -        self.check_sections(ln, declaration_name, "function", self.entry.sectcheck)
> +        self.check_sections(ln, declaration_name, "function")
>  
>          self.check_return_section(ln, declaration_name, return_type)
>  



Thanks,
Mauro