Re: [PATCH 2/9] docs: kdoc: consolidate the "begin section" logic

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

Em Sat, 21 Jun 2025 14:35:05 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Pull the repeated "begin a section" logic into a single place and hide it
> within the KernelEntry class.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Heh, I had a code snippet similar to this one on one of my test branches ;-)

LGTM.

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

> ---
>  scripts/lib/kdoc/kdoc_parser.py | 32 +++++++++++++++++---------------
>  1 file changed, 17 insertions(+), 15 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index c46e1b6a7d4b..d29a61a06f6d 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -169,6 +169,15 @@ class KernelEntry:
>          self.warnings.append(log_msg)
>          return
>  
> +    #
> +    # Begin a new section.
> +    #
> +    def begin_section(self, line_no, title = SECTION_DEFAULT, dump = False):
> +        if dump:
> +            self.dump_section(start_new = True)
> +        self.section = title
> +        self.new_start_line = line_no
> +
>      def dump_section(self, start_new=True):
>          """
>          Dumps section contents to arrays/hashes intended for that purpose.
> @@ -1231,12 +1240,11 @@ class KernelDoc:
>          # Check for a DOC: block and handle them specially.
>          #
>          if doc_block.search(line):
> -            self.entry.new_start_line = ln
>  
>              if not doc_block.group(1):
> -                self.entry.section = "Introduction"
> +                self.entry.begin_section(ln, "Introduction")
>              else:
> -                self.entry.section = doc_block.group(1)
> +                self.entry.begin_section(ln, doc_block.group(1))
>  
>              self.entry.identifier = self.entry.section
>              self.state = state.DOCBLOCK
> @@ -1270,8 +1278,7 @@ class KernelDoc:
>              self.state = state.BODY
>              self.entry.identifier = self.entry.identifier.strip(" ")
>              # if there's no @param blocks need to set up default section here
> -            self.entry.section = SECTION_DEFAULT
> -            self.entry.new_start_line = ln + 1
> +            self.entry.begin_section(ln + 1)
>              #
>              # Find the description portion, which *should* be there but
>              # isn't always.
> @@ -1312,8 +1319,7 @@ class KernelDoc:
>              r = KernRe(r"\s*\*\s*\S")
>              if r.match(line):
>                  self.dump_section()
> -                self.entry.section = SECTION_DEFAULT
> -                self.entry.new_start_line = ln
> +                self.entry.begin_section(ln)
>                  self.entry.contents = ""
>  
>          if doc_sect.search(line):
> @@ -1340,8 +1346,7 @@ class KernelDoc:
>              if self.entry.contents.strip("\n"):
>                  self.dump_section()
>  
> -            self.entry.new_start_line = ln
> -            self.entry.section = newsection
> +            self.entry.begin_section(ln, newsection)
>              self.entry.leading_space = None
>  
>              self.entry.contents = newcontents.lstrip()
> @@ -1370,9 +1375,7 @@ class KernelDoc:
>  
>              if cont == "":
>                  if self.entry.section == self.section_context:
> -                    self.dump_section()
> -
> -                    self.entry.new_start_line = ln
> +                    self.entry.begin_section(ln, dump = True)
>                      self.state = state.BODY
>                  else:
>                      if self.entry.section != SECTION_DEFAULT:
> @@ -1427,8 +1430,7 @@ class KernelDoc:
>  
>          if self.inline_doc_state == state.INLINE_NAME and \
>             doc_inline_sect.search(line):
> -            self.entry.section = doc_inline_sect.group(1)
> -            self.entry.new_start_line = ln
> +            self.entry.begin_section(ln, doc_inline_sect.group(1))
>  
>              self.entry.contents = doc_inline_sect.group(2).lstrip()
>              if self.entry.contents != "":
> @@ -1627,7 +1629,7 @@ class KernelDoc:
>          """STATE_PROTO: reading a function/whatever prototype."""
>  
>          if doc_inline_oneline.search(line):
> -            self.entry.section = doc_inline_oneline.group(1)
> +            self.entry.begin_section(ln, doc_inline_oneline.group(1))
>              self.entry.contents = doc_inline_oneline.group(2)
>  
>              if self.entry.contents != "":



Thanks,
Mauro