admin/linux
1
0
Fork 0
mirror of https://github.com/torvalds/linux.git synced 2025-12-07 20:06:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: kdoc: Coalesce parameter-list handling

Browse Source 
Callers to output_declaration() always pass the parameter information from
self.entry; remove all of the boilerplate arguments and just get at that
information directly.  Formalize its placement in the KdocItem class.

It would be nice to get rid of parameterlist as well, but that has the
effect of reordering the output of function parameters and struct fields to
match the order in the kerneldoc comment rather than in the declaration.
One could argue about which is more correct, but the ordering has been left
unchanged for now.

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 13:05:56 -06:00
parent efacdf8513
commit de6f7ac91a
3 changed files with 43 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
scripts/lib/kdoc/kdoc_item.py
View File

@@ -11,6 +11,10 @@ class KdocItem:
self.declaration_start_line = start_line self.declaration_start_line = start_line
self.sections = {} self.sections = {}
self.sections_start_lines = {} self.sections_start_lines = {}
self.parameterlist = []
self.parameterdesc_start_lines = []
self.parameterdescs = {}
self.parametertypes = {}
# #
# Just save everything else into our own dict so that the output # 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 # side can grab it directly as before. As we move things into more
@@ -28,8 +32,14 @@ class KdocItem:
return self.get(key) return self.get(key)
# #
# Tracking of section information. # Tracking of section and parameter information.
# #
def set_sections(self, sections, start_lines): def set_sections(self, sections, start_lines):
self.sections = sections self.sections = sections
self.section_start_lines = start_lines self.section_start_lines = start_lines
def set_params(self, names, descs, types, starts):
self.parameterlist = names
self.parameterdescs = descs
self.parametertypes = types
self.parameterdesc_start_lines = starts

75
scripts/lib/kdoc/kdoc_output.py
View File

@@ -373,18 +373,13 @@ class RestFormat(OutputFormat):
signature = args['functiontype'] + " " signature = args['functiontype'] + " "
signature += args['function'] + " (" signature += args['function'] + " ("
parameterlist = args.get('parameterlist', [])
parameterdescs = args.get('parameterdescs', {})
parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
ln = args.get('declaration_start_line', 0) ln = args.get('declaration_start_line', 0)
count = 0 count = 0
for parameter in parameterlist: for parameter in args.parameterlist:
if count != 0: if count != 0:
signature += ", " signature += ", "
count += 1 count += 1
dtype = args['parametertypes'].get(parameter, "") dtype = args.parametertypes.get(parameter, "")
if function_pointer.search(dtype): if function_pointer.search(dtype):
signature += function_pointer.group(1) + parameter + function_pointer.group(3) signature += function_pointer.group(1) + parameter + function_pointer.group(3)
@@ -419,26 +414,26 @@ class RestFormat(OutputFormat):
# function prototypes apart # function prototypes apart
self.lineprefix = " " self.lineprefix = " "
if parameterlist: if args.parameterlist:
self.data += ".. container:: kernelindent\n\n" self.data += ".. container:: kernelindent\n\n"
self.data += f"{self.lineprefix}**Parameters**\n\n" self.data += f"{self.lineprefix}**Parameters**\n\n"
for parameter in parameterlist: for parameter in args.parameterlist:
parameter_name = KernRe(r'\[.*').sub('', parameter) parameter_name = KernRe(r'\[.*').sub('', parameter)
dtype = args['parametertypes'].get(parameter, "") dtype = args.parametertypes.get(parameter, "")
if dtype: if dtype:
self.data += f"{self.lineprefix}``{dtype}``\n" self.data += f"{self.lineprefix}``{dtype}``\n"
else: else:
self.data += f"{self.lineprefix}``{parameter}``\n" self.data += f"{self.lineprefix}``{parameter}``\n"
self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0)) self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
self.lineprefix = " " self.lineprefix = " "
if parameter_name in parameterdescs and \ if parameter_name in args.parameterdescs and \
parameterdescs[parameter_name] != KernelDoc.undescribed: args.parameterdescs[parameter_name] != KernelDoc.undescribed:
self.output_highlight(parameterdescs[parameter_name]) self.output_highlight(args.parameterdescs[parameter_name])
self.data += "\n" self.data += "\n"
else: else:
self.data += f"{self.lineprefix}*undescribed*\n\n" self.data += f"{self.lineprefix}*undescribed*\n\n"
@@ -451,8 +446,6 @@ class RestFormat(OutputFormat):
oldprefix = self.lineprefix oldprefix = self.lineprefix
name = args.get('enum', '') name = args.get('enum', '')
parameterlist = args.get('parameterlist', [])
parameterdescs = args.get('parameterdescs', {})
ln = args.get('declaration_start_line', 0) ln = args.get('declaration_start_line', 0)
self.data += f"\n\n.. c:enum:: {name}\n\n" self.data += f"\n\n.. c:enum:: {name}\n\n"
@@ -467,11 +460,11 @@ class RestFormat(OutputFormat):
self.lineprefix = outer + " " self.lineprefix = outer + " "
self.data += f"{outer}**Constants**\n\n" self.data += f"{outer}**Constants**\n\n"
for parameter in parameterlist: for parameter in args.parameterlist:
self.data += f"{outer}``{parameter}``\n" self.data += f"{outer}``{parameter}``\n"
if parameterdescs.get(parameter, '') != KernelDoc.undescribed: if args.parameterdescs.get(parameter, '') != KernelDoc.undescribed:
self.output_highlight(parameterdescs[parameter]) self.output_highlight(args.parameterdescs[parameter])
else: else:
self.data += f"{self.lineprefix}*undescribed*\n\n" self.data += f"{self.lineprefix}*undescribed*\n\n"
self.data += "\n" self.data += "\n"
@@ -505,10 +498,6 @@ class RestFormat(OutputFormat):
dtype = args.get('type', "struct") dtype = args.get('type', "struct")
ln = args.get('declaration_start_line', 0) ln = args.get('declaration_start_line', 0)
parameterlist = args.get('parameterlist', [])
parameterdescs = args.get('parameterdescs', {})
parameterdesc_start_lines = args.get('parameterdesc_start_lines', {})
self.data += f"\n\n.. c:{dtype}:: {name}\n\n" self.data += f"\n\n.. c:{dtype}:: {name}\n\n"
self.print_lineno(ln) self.print_lineno(ln)
@@ -531,21 +520,21 @@ class RestFormat(OutputFormat):
self.lineprefix = " " self.lineprefix = " "
self.data += f"{self.lineprefix}**Members**\n\n" self.data += f"{self.lineprefix}**Members**\n\n"
for parameter in parameterlist: for parameter in args.parameterlist:
if not parameter or parameter.startswith("#"): if not parameter or parameter.startswith("#"):
continue continue
parameter_name = parameter.split("[", maxsplit=1)[0] parameter_name = parameter.split("[", maxsplit=1)[0]
if parameterdescs.get(parameter_name) == KernelDoc.undescribed: if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
continue continue
self.print_lineno(parameterdesc_start_lines.get(parameter_name, 0)) self.print_lineno(args.parameterdesc_start_lines.get(parameter_name, 0))
self.data += f"{self.lineprefix}``{parameter}``\n" self.data += f"{self.lineprefix}``{parameter}``\n"
self.lineprefix = " " self.lineprefix = " "
self.output_highlight(parameterdescs[parameter_name]) self.output_highlight(args.parameterdescs[parameter_name])
self.lineprefix = " " self.lineprefix = " "
self.data += "\n" self.data += "\n"
@@ -643,9 +632,6 @@ class ManFormat(OutputFormat):
def out_function(self, fname, name, args): def out_function(self, fname, name, args):
"""output function in man""" """output function in man"""
parameterlist = args.get('parameterlist', [])
parameterdescs = args.get('parameterdescs', {})
self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" self.data += f'.TH "{args["function"]}" 9 "{args["function"]}" "{self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n"
self.data += ".SH NAME\n" self.data += ".SH NAME\n"
@@ -661,11 +647,11 @@ class ManFormat(OutputFormat):
parenth = "(" parenth = "("
post = "," post = ","
for parameter in parameterlist: for parameter in args.parameterlist:
if count == len(parameterlist) - 1: if count == len(args.parameterlist) - 1:
post = ");" post = ");"
dtype = args['parametertypes'].get(parameter, "") dtype = args.parametertypes.get(parameter, "")
if function_pointer.match(dtype): if function_pointer.match(dtype):
# Pointer-to-function # Pointer-to-function
self.data += f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"' + "\n" self.data += f'".BI "{parenth}{function_pointer.group(1)}" " ") ({function_pointer.group(2)}){post}"' + "\n"
@@ -676,14 +662,14 @@ class ManFormat(OutputFormat):
count += 1 count += 1
parenth = "" parenth = ""
if parameterlist: if args.parameterlist:
self.data += ".SH ARGUMENTS\n" self.data += ".SH ARGUMENTS\n"
for parameter in parameterlist: for parameter in args.parameterlist:
parameter_name = re.sub(r'\[.*', '', parameter) parameter_name = re.sub(r'\[.*', '', parameter)
self.data += f'.IP "{parameter}" 12' + "\n" self.data += f'.IP "{parameter}" 12' + "\n"
self.output_highlight(parameterdescs.get(parameter_name, "")) self.output_highlight(args.parameterdescs.get(parameter_name, ""))
for section, text in args.sections.items(): for section, text in args.sections.items():
self.data += f'.SH "{section.upper()}"' + "\n" self.data += f'.SH "{section.upper()}"' + "\n"
@@ -692,7 +678,6 @@ class ManFormat(OutputFormat):
def out_enum(self, fname, name, args): def out_enum(self, fname, name, args):
name = args.get('enum', '') name = args.get('enum', '')
parameterlist = args.get('parameterlist', [])
self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n" self.data += f'.TH "{self.modulename}" 9 "enum {args["enum"]}" "{self.man_date}" "API Manual" LINUX' + "\n"
@@ -703,9 +688,9 @@ class ManFormat(OutputFormat):
self.data += f"enum {args['enum']}" + " {\n" self.data += f"enum {args['enum']}" + " {\n"
count = 0 count = 0
for parameter in parameterlist: for parameter in args.parameterlist:
self.data += f'.br\n.BI " {parameter}"' + "\n" self.data += f'.br\n.BI " {parameter}"' + "\n"
if count == len(parameterlist) - 1: if count == len(args.parameterlist) - 1:
self.data += "\n};\n" self.data += "\n};\n"
else: else:
self.data += ", \n.br\n" self.data += ", \n.br\n"
@@ -714,10 +699,10 @@ class ManFormat(OutputFormat):
self.data += ".SH Constants\n" self.data += ".SH Constants\n"
for parameter in parameterlist: for parameter in args.parameterlist:
parameter_name = KernRe(r'\[.*').sub('', parameter) parameter_name = KernRe(r'\[.*').sub('', parameter)
self.data += f'.IP "{parameter}" 12' + "\n" self.data += f'.IP "{parameter}" 12' + "\n"
self.output_highlight(args['parameterdescs'].get(parameter_name, "")) self.output_highlight(args.parameterdescs.get(parameter_name, ""))
for section, text in args.sections.items(): for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n" self.data += f'.SH "{section}"' + "\n"
@@ -743,8 +728,6 @@ class ManFormat(OutputFormat):
struct_name = args.get('struct') struct_name = args.get('struct')
purpose = args.get('purpose') purpose = args.get('purpose')
definition = args.get('definition') definition = args.get('definition')
parameterlist = args.get('parameterlist', [])
parameterdescs = args.get('parameterdescs', {})
self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n" self.data += f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_date}" "API Manual" LINUX' + "\n"
@@ -760,17 +743,17 @@ class ManFormat(OutputFormat):
self.data += f'.BI "{declaration}\n' + "};\n.br\n\n" self.data += f'.BI "{declaration}\n' + "};\n.br\n\n"
self.data += ".SH Members\n" self.data += ".SH Members\n"
for parameter in parameterlist: for parameter in args.parameterlist:
if parameter.startswith("#"): if parameter.startswith("#"):
continue continue
parameter_name = re.sub(r"\[.*", "", parameter) parameter_name = re.sub(r"\[.*", "", parameter)
if parameterdescs.get(parameter_name) == KernelDoc.undescribed: if args.parameterdescs.get(parameter_name) == KernelDoc.undescribed:
continue continue
self.data += f'.IP "{parameter}" 12' + "\n" self.data += f'.IP "{parameter}" 12' + "\n"
self.output_highlight(parameterdescs.get(parameter_name)) self.output_highlight(args.parameterdescs.get(parameter_name))
for section, text in args.sections.items(): for section, text in args.sections.items():
self.data += f'.SH "{section}"' + "\n" self.data += f'.SH "{section}"' + "\n"

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

@@ -278,7 +278,9 @@ class KernelDoc:
if section in sections and not sections[section].rstrip(): if section in sections and not sections[section].rstrip():
del sections[section] del sections[section]
item.set_sections(sections, self.entry.section_start_lines) item.set_sections(sections, self.entry.section_start_lines)
item.set_params(self.entry.parameterlist, self.entry.parameterdescs,
self.entry.parametertypes,
self.entry.parameterdesc_start_lines)
self.entries.append(item) self.entries.append(item)
self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args)) self.config.log.debug("Output: %s:%s = %s", dtype, name, pformat(args))
@@ -790,10 +792,6 @@ class KernelDoc:
self.output_declaration(decl_type, declaration_name, self.output_declaration(decl_type, declaration_name,
struct=declaration_name, struct=declaration_name,
definition=declaration, definition=declaration,
parameterlist=self.entry.parameterlist,
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose) purpose=self.entry.declaration_purpose)
def dump_enum(self, ln, proto): def dump_enum(self, ln, proto):
@@ -873,9 +871,6 @@ class KernelDoc:
self.output_declaration('enum', declaration_name, self.output_declaration('enum', declaration_name,
enum=declaration_name, enum=declaration_name,
parameterlist=self.entry.parameterlist,
parameterdescs=self.entry.parameterdescs,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose) purpose=self.entry.declaration_purpose)
def dump_declaration(self, ln, prototype): def dump_declaration(self, ln, prototype):
@@ -1039,10 +1034,6 @@ class KernelDoc:
function=declaration_name, function=declaration_name,
typedef=True, typedef=True,
functiontype=return_type, functiontype=return_type,
parameterlist=self.entry.parameterlist,
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose, purpose=self.entry.declaration_purpose,
func_macro=func_macro) func_macro=func_macro)
else: else:
@@ -1050,10 +1041,6 @@ class KernelDoc:
function=declaration_name, function=declaration_name,
typedef=False, typedef=False,
functiontype=return_type, functiontype=return_type,
parameterlist=self.entry.parameterlist,
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose, purpose=self.entry.declaration_purpose,
func_macro=func_macro) func_macro=func_macro)
@@ -1093,10 +1080,6 @@ class KernelDoc:
function=declaration_name, function=declaration_name,
typedef=True, typedef=True,
functiontype=return_type, functiontype=return_type,
parameterlist=self.entry.parameterlist,
parameterdescs=self.entry.parameterdescs,
parametertypes=self.entry.parametertypes,
parameterdesc_start_lines=self.entry.parameterdesc_start_lines,
purpose=self.entry.declaration_purpose) purpose=self.entry.declaration_purpose)
return return