Em Sat, 21 Jun 2025 14:35:09 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> Move the recognition of this state to when we enter it, rather than when we
> exit, eliminating some twisty logic along the way.
>
> Some changes in output do result from this shift, generally for kerneldoc
> comments that do not quite fit the format. See, for example,
> struct irqdomain. As far as I can tell, the new behavior is more correct
> in each case.
>
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
LGTM.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
> scripts/lib/kdoc/kdoc_parser.py | 48 ++++++++++++++-------------------
> 1 file changed, 20 insertions(+), 28 deletions(-)
>
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index a336d543e72b..5998b02ca3a0 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1316,21 +1316,25 @@ class KernelDoc:
> def is_new_section(self, ln, line):
> if doc_sect.search(line):
> self.entry.in_doc_sect = True
> + self.state = state.BODY
> + #
> + # Pick out the name of our new section, tweaking it if need be.
> + #
> newsection = doc_sect.group(1)
> -
> - if newsection.lower() in ["description", "context"]:
> - newsection = newsection.title()
> -
> - # Special case: @return is a section, not a param description
> - if newsection.lower() in ["@return", "@returns",
> - "return", "returns"]:
> + if newsection.lower() == 'description':
> + newsection = 'Description'
> + elif newsection.lower() == 'context':
> + newsection = 'Context'
> + self.state = state.SPECIAL_SECTION
> + elif newsection.lower() in ["@return", "@returns",
> + "return", "returns"]:
> newsection = "Return"
> -
> - # Perl kernel-doc has a check here for contents before sections.
> - # the logic there is always false, as in_doc_sect variable is
> - # always true. So, just don't implement Wcontents_before_sections
> -
> - # .title()
> + self.state = state.SPECIAL_SECTION
> + elif newsection[0] == '@':
> + self.state = state.SPECIAL_SECTION
> + #
> + # Initialize the contents, and get the new section going.
> + #
> newcontents = doc_sect.group(2)
> if not newcontents:
> newcontents = ""
> @@ -1344,8 +1348,6 @@ class KernelDoc:
> self.entry.contents = newcontents.lstrip()
> if self.entry.contents:
> self.entry.contents += "\n"
> -
> - self.state = state.BODY
> return True
> return False
>
> @@ -1395,8 +1397,9 @@ class KernelDoc:
> """
> STATE_SPECIAL_SECTION: a section ending with a blank line
> """
> - if KernRe(r"\s*\*\s*\S").match(line):
> + if KernRe(r"\s*\*\s*$").match(line):
> self.entry.begin_section(ln, dump = True)
> + self.state = state.BODY
> self.process_body(ln, line)
>
> def process_body(self, ln, line):
> @@ -1424,20 +1427,9 @@ class KernelDoc:
> cont = doc_content.group(1)
>
> if cont == "":
> - if self.entry.section == self.section_context:
> - self.entry.begin_section(ln, dump = True)
> - self.state = state.BODY
> - else:
> - if self.entry.section != SECTION_DEFAULT:
> - self.state = state.SPECIAL_SECTION
> - else:
> - self.state = state.BODY
> -
> self.entry.contents += "\n"
> -
> else:
> - if self.entry.section.startswith('@') or \
> - self.entry.section == self.section_context:
> + if self.state == state.SPECIAL_SECTION:
> if self.entry.leading_space is None:
> r = KernRe(r'^(\s+)')
> if r.match(cont):
Thanks,
Mauro
