rjmcmahon
/
umber-kernel
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

docs: kdoc: clean up check_sections() 

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.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet 2025-07-02 14:53:32 -06:00
parent bd5628bf60
commit 636d4d9ec6
1 changed files with 11 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
scripts/lib/kdoc/kdoc_parser.py
View File

@ -42,9 +42,11 @@ doc_decl = doc_com + KernRe(r'(\w+)', cache=False)
# @{section-name}: # @{section-name}:
# while trying to not match literal block starts like "example::" # 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 + \ doc_sect = doc_com + \
KernRe(r'\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$', KernRe(r'\s*(\@[.\w]+|\@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
flags=re.I, cache=False) flags=re.I, cache=False)
doc_content = doc_com_body + KernRe(r'(.*)', cache=False) doc_content = doc_com_body + KernRe(r'(.*)', cache=False)
doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False) doc_inline_start = KernRe(r'^\s*/\*\*\s*$', cache=False)
@ -115,7 +117,6 @@ class KernelEntry:
self.config = config self.config = config
self._contents = [] self._contents = []
self.sectcheck = ""
self.prototype = "" self.prototype = ""
self.warnings = [] self.warnings = []
@ -187,7 +188,6 @@ class KernelEntry:
self.parameterdescs[name] = contents self.parameterdescs[name] = contents
self.parameterdesc_start_lines[name] = self.new_start_line self.parameterdesc_start_lines[name] = self.new_start_line
self.sectcheck += name + " "
self.new_start_line = 0 self.new_start_line = 0
else: else:
@ -478,29 +478,20 @@ class KernelDoc:
self.push_parameter(ln, decl_type, param, dtype, self.push_parameter(ln, decl_type, param, dtype,
arg, declaration_name) 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 Check for errors inside sections, emitting warnings if not found
parameters are described. parameters are described.
""" """
for section in self.entry.sections:
sects = sectcheck.split() if section not in self.entry.parameterlist and \
not known_sections.search(section):
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:
if decl_type == 'function': if decl_type == 'function':
dname = f"{decl_type} parameter" dname = f"{decl_type} parameter"
else: else:
dname = f"{decl_type} member" dname = f"{decl_type} member"
self.emit_msg(ln, 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): def check_return_section(self, ln, declaration_name, return_type):
""" """
@ -754,7 +745,7 @@ class KernelDoc:
self.create_parameter_list(ln, decl_type, members, ';', self.create_parameter_list(ln, decl_type, members, ';',
declaration_name) 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 # Adjust declaration for better display
declaration = KernRe(r'([\{;])').sub(r'\1\n', declaration) 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") f"expecting prototype for {self.entry.identifier}(). Prototype was for {declaration_name}() instead")
return 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) self.check_return_section(ln, declaration_name, return_type)