From nobody Sun Feb 8 15:46:34 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D065B24A066; Mon, 24 Feb 2025 09:09:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1740388143; cv=none; b=b8+EA7rm8izNn34gP5YNDh7CpsNcdhs+hwMYd8EYOkwy4JBURy2ATv7wPtCE8Up2Dix6uCJ0M6mNSs6h6x3lWcfEI5dik7l4CTpPgQ1+ez9Q1fnmu+zYWv3Odh18oipM4Fj9yyDGP8wcGiURZ5+NtVOzeBLH0JSbJdHjeahrFr0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1740388143; c=relaxed/simple; bh=+233tNh0yGNXfYZxQx+uxFiZ7ugw73yF3W1jWprPI1A=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=hbEUk0TfUaXfRkCSpKh7lRDmIqSkOj/3llBeOZmpPiyZOidxofJhqqkhgJT20unX9Fi8MFTVvcigldAfvCDlztvKRsTQtzMBc96Gatx1y1x3Qnwz4L8AnvNt9rORkW000/V8o0himmS0wbN7fWna0HHFmWq2U+2un0ZCislGXmw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ao+6ySxy; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ao+6ySxy" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 0096FC113CF; Mon, 24 Feb 2025 09:09:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1740388143; bh=+233tNh0yGNXfYZxQx+uxFiZ7ugw73yF3W1jWprPI1A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ao+6ySxy2zzGXgZD5+bRUiuFjIt4gIU67lH3Cnkw2+Hgzm2kHOClv7YkHaKyKuatd YPMfrjhEKuztSCohG59M4AxWSr2xNHwyB7O4hhWCiVbogD31ZyeKgLZ0MwaCzcwYFF 16q3a3aK/5k89B0pXIC+jZpMTL52tnPBZU1gXtwoytF3OfKhRSdb86qdeUZhyJmsQB wPH31iLtnc4RifEPHc3P7T9PjCRZHrxtM2UCz89lTmM+1ianlvJz4V02oPvzWcV+/F yHL2pIHi9i2pOt9Sk2P/E/PZeJqTR4SDL5Mnz5iTaG1RnPcTwt+GyEVMvNISXGrk5T q0s8rhHAMerNA== Received: from mchehab by mail.kernel.org with local (Exim 4.98) (envelope-from ) id 1tmUST-00000003p4W-15Mq; Mon, 24 Feb 2025 10:09:01 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , "Mauro Carvalho Chehab" , linux-kernel@vger.kernel.org Subject: [PATCH v2 17/39] scripts/kernel-doc.py: convert message output to an interactor Date: Mon, 24 Feb 2025 10:08:23 +0100 Message-ID: <2b5ecc8328cdb8a37e7ff084dae89a82a532e49a.1740387599.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: Mauro Carvalho Chehab Content-Type: text/plain; charset="utf-8" Instead of directly printing output messages, change kdoc classes to return an interactor with the output message, letting the actual display to happen at the command-line command. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc.py | 9 +- scripts/lib/kdoc/kdoc_files.py | 15 ++- scripts/lib/kdoc/kdoc_output.py | 171 ++++++++++++++++---------------- 3 files changed, 104 insertions(+), 91 deletions(-) diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py index 0596c711d448..6c3179a2da65 100755 --- a/scripts/kernel-doc.py +++ b/scripts/kernel-doc.py @@ -208,9 +208,12 @@ def main(): =20 kfiles.parse() =20 - kfiles.msg(enable_lineno=3Dargs.enable_lineno, export=3Dargs.export, - internal=3Dargs.internal, symbol=3Dargs.symbol, - nosymbol=3Dargs.nosymbol) + for t in kfiles.msg(enable_lineno=3Dargs.enable_lineno, export=3Dargs.= export, + internal=3Dargs.internal, symbol=3Dargs.symbol, + nosymbol=3Dargs.nosymbol): + msg =3D t[1] + if msg: + print(msg) =20 =20 # Call main method diff --git a/scripts/lib/kdoc/kdoc_files.py b/scripts/lib/kdoc/kdoc_files.py index 76dd53611c08..434fc66a9dad 100755 --- a/scripts/lib/kdoc/kdoc_files.py +++ b/scripts/lib/kdoc/kdoc_files.py @@ -228,9 +228,10 @@ class KernelFiles(): =20 def out_msg(self, fname, name, arg): """ - Output messages from a file name using the output style filtering. + Return output messages from a file name using the output style + filtering. =20 - If output type was not handled by the syler, return False. + If output type was not handled by the syler, return None. """ =20 # NOTE: we can add rules here to filter out unwanted parts, @@ -241,7 +242,8 @@ class KernelFiles(): def msg(self, enable_lineno=3DFalse, export=3DFalse, internal=3DFalse, symbol=3DNone, nosymbol=3DNone): """ - Interacts over the kernel-doc results and output messages. + Interacts over the kernel-doc results and output messages, + returning kernel-doc markups on each interaction """ =20 function_table =3D self.config.function_table @@ -260,10 +262,15 @@ class KernelFiles(): function_table, enable_lineno) =20 for fname, arg_tuple in self.results: + msg =3D "" for name, arg in arg_tuple: - if self.out_msg(fname, name, arg): + msg +=3D self.out_msg(fname, name, arg) + + if msg is None: ln =3D arg.get("ln", 0) dtype =3D arg.get('type', "") =20 self.config.log.warning("%s:%d Can't handle %s", fname, ln, dtype) + if msg: + yield fname, msg diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index d080440caa1c..91f6e356d03d 100755 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -70,6 +70,8 @@ class OutputFormat: self.function_table =3D set() self.config =3D None =20 + self.data =3D "" + def set_config(self, config): self.config =3D config =20 @@ -156,37 +158,38 @@ class OutputFormat: return True =20 def msg(self, fname, name, args): + self.data =3D "" =20 dtype =3D args.get('type', "") =20 if dtype =3D=3D "doc": self.out_doc(fname, name, args) - return False + return self.data =20 if not self.check_declaration(dtype, name): - return False + return self.data =20 if dtype =3D=3D "function": self.out_function(fname, name, args) - return False + return self.data =20 if dtype =3D=3D "enum": self.out_enum(fname, name, args) - return False + return self.data =20 if dtype =3D=3D "typedef": self.out_typedef(fname, name, args) - return False + return self.data =20 if dtype in ["struct", "union"]: self.out_struct(fname, name, args) - return False + return self.data =20 # Warn if some type requires an output logic self.config.log.warning("doesn't now how to output '%s' block", dtype) =20 - return True + return None =20 # Virtual methods to be overridden by inherited classes def out_doc(self, fname, name, args): @@ -247,7 +250,7 @@ class RestFormat(OutputFormat): """Outputs a line number""" =20 if self.enable_lineno and ln: - print(f".. LINENO {ln}") + self.data +=3D f".. LINENO {ln}\n" =20 def output_highlight(self, args): input_text =3D args @@ -294,7 +297,7 @@ class RestFormat(OutputFormat): =20 # Print the output with the line prefix for line in output.strip("\n").split("\n"): - print(self.lineprefix + line) + self.data +=3D self.lineprefix + line + "\n" =20 def out_section(self, args, out_reference=3DFalse): """ @@ -316,15 +319,15 @@ class RestFormat(OutputFormat): =20 if not self.out_mode =3D=3D self.OUTPUT_INCLUDE: if out_reference: - print(f".. _{section}:\n") + self.data +=3D f".. _{section}:\n\n" =20 if not self.symbol: - print(f'{self.lineprefix}**{section}**\n') + self.data +=3D f'{self.lineprefix}**{section}**\n\n' =20 self.print_lineno(section_start_lines.get(section, 0)) self.output_highlight(sections[section]) - print() - print() + self.data +=3D "\n" + self.data +=3D "\n" =20 def out_doc(self, fname, name, args): if not self.check_doc(name): @@ -367,42 +370,42 @@ class RestFormat(OutputFormat): signature +=3D ")" =20 if args.get('typedef') or not args.get('functiontype'): - print(f".. c:macro:: {args['function']}\n") + self.data +=3D f".. c:macro:: {args['function']}\n\n" =20 if args.get('typedef'): self.print_lineno(ln) - print(" **Typedef**: ", end=3D"") + self.data +=3D " **Typedef**: " self.lineprefix =3D "" self.output_highlight(args.get('purpose', "")) - print("\n\n**Syntax**\n") - print(f" ``{signature}``\n") + self.data +=3D "\n\n**Syntax**\n\n" + self.data +=3D f" ``{signature}``\n\n" else: - print(f"``{signature}``\n") + self.data +=3D f"``{signature}``\n\n" else: - print(f".. c:function:: {signature}\n") + self.data +=3D f".. c:function:: {signature}\n\n" =20 if not args.get('typedef'): self.print_lineno(ln) self.lineprefix =3D " " self.output_highlight(args.get('purpose', "")) - print() + self.data +=3D "\n" =20 # Put descriptive text into a container (HTML
) to help set # function prototypes apart self.lineprefix =3D " " =20 if parameterlist: - print(".. container:: kernelindent\n") - print(f"{self.lineprefix}**Parameters**\n") + self.data +=3D ".. container:: kernelindent\n\n" + self.data +=3D f"{self.lineprefix}**Parameters**\n\n" =20 for parameter in parameterlist: parameter_name =3D Re(r'\[.*').sub('', parameter) dtype =3D args['parametertypes'].get(parameter, "") =20 if dtype: - print(f"{self.lineprefix}``{dtype}``") + self.data +=3D f"{self.lineprefix}``{dtype}``\n" else: - print(f"{self.lineprefix}``{parameter}``") + self.data +=3D f"{self.lineprefix}``{parameter}``\n" =20 self.print_lineno(parameterdesc_start_lines.get(parameter_name= , 0)) =20 @@ -411,9 +414,9 @@ class RestFormat(OutputFormat): parameterdescs[parameter_name] !=3D KernelDoc.undescribed: =20 self.output_highlight(parameterdescs[parameter_name]) - print() + self.data +=3D "\n" else: - print(f"{self.lineprefix}*undescribed*\n") + self.data +=3D f"{self.lineprefix}*undescribed*\n\n" self.lineprefix =3D " " =20 self.out_section(args) @@ -427,26 +430,26 @@ class RestFormat(OutputFormat): parameterdescs =3D args.get('parameterdescs', {}) ln =3D args.get('ln', 0) =20 - print(f"\n\n.. c:enum:: {name}\n") + self.data +=3D f"\n\n.. c:enum:: {name}\n\n" =20 self.print_lineno(ln) self.lineprefix =3D " " self.output_highlight(args.get('purpose', '')) - print() + self.data +=3D "\n" =20 - print(".. container:: kernelindent\n") + self.data +=3D ".. container:: kernelindent\n\n" outer =3D self.lineprefix + " " self.lineprefix =3D outer + " " - print(f"{outer}**Constants**\n") + self.data +=3D f"{outer}**Constants**\n\n" =20 for parameter in parameterlist: - print(f"{outer}``{parameter}``") + self.data +=3D f"{outer}``{parameter}``\n" =20 if parameterdescs.get(parameter, '') !=3D KernelDoc.undescribe= d: self.output_highlight(parameterdescs[parameter]) else: - print(f"{self.lineprefix}*undescribed*\n") - print() + self.data +=3D f"{self.lineprefix}*undescribed*\n\n" + self.data +=3D "\n" =20 self.lineprefix =3D oldprefix self.out_section(args) @@ -457,14 +460,14 @@ class RestFormat(OutputFormat): name =3D args.get('typedef', '') ln =3D args.get('ln', 0) =20 - print(f"\n\n.. c:type:: {name}\n") + self.data +=3D f"\n\n.. c:type:: {name}\n\n" =20 self.print_lineno(ln) self.lineprefix =3D " " =20 self.output_highlight(args.get('purpose', '')) =20 - print() + self.data +=3D "\n" =20 self.lineprefix =3D oldprefix self.out_section(args) @@ -481,7 +484,7 @@ class RestFormat(OutputFormat): parameterdescs =3D args.get('parameterdescs', {}) parameterdesc_start_lines =3D args.get('parameterdesc_start_lines'= , {}) =20 - print(f"\n\n.. c:{dtype}:: {name}\n") + self.data +=3D f"\n\n.. c:{dtype}:: {name}\n\n" =20 self.print_lineno(ln) =20 @@ -489,20 +492,20 @@ class RestFormat(OutputFormat): self.lineprefix +=3D " " =20 self.output_highlight(purpose) - print() + self.data +=3D "\n" =20 - print(".. container:: kernelindent\n") - print(f"{self.lineprefix}**Definition**::\n") + self.data +=3D ".. container:: kernelindent\n\n" + self.data +=3D f"{self.lineprefix}**Definition**::\n\n" =20 self.lineprefix =3D self.lineprefix + " " =20 declaration =3D declaration.replace("\t", self.lineprefix) =20 - print(f"{self.lineprefix}{dtype} {name}" + ' {') - print(f"{declaration}{self.lineprefix}" + "};\n") + self.data +=3D f"{self.lineprefix}{dtype} {name}" + ' {' + "\n" + self.data +=3D f"{declaration}{self.lineprefix}" + "};\n\n" =20 self.lineprefix =3D " " - print(f"{self.lineprefix}**Members**\n") + self.data +=3D f"{self.lineprefix}**Members**\n\n" for parameter in parameterlist: if not parameter or parameter.startswith("#"): continue @@ -514,15 +517,15 @@ class RestFormat(OutputFormat): =20 self.print_lineno(parameterdesc_start_lines.get(parameter_name= , 0)) =20 - print(f"{self.lineprefix}``{parameter}``") + self.data +=3D f"{self.lineprefix}``{parameter}``\n" =20 self.lineprefix =3D " " self.output_highlight(parameterdescs[parameter_name]) self.lineprefix =3D " " =20 - print() + self.data +=3D "\n" =20 - print() + self.data +=3D "\n" =20 self.lineprefix =3D oldprefix self.out_section(args) @@ -575,19 +578,19 @@ class ManFormat(OutputFormat): line =3D Re(r"^\s*").sub("", line) =20 if line and line[0] =3D=3D ".": - print("\\&" + line) + self.data +=3D "\\&" + line + "\n" else: - print(line) + self.data +=3D line + "\n" =20 def out_doc(self, fname, name, args): module =3D args.get('module') sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - print(f'.TH "{module}" 9 "{module}" "{self.man_date}" "API Manual"= LINUX') + self.data +=3D f'.TH "{module}" 9 "{module}" "{self.man_date}" "AP= I Manual" LINUX' + "\n" =20 for section in sectionlist: - print(f'.SH "{section}"') + self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections.get(section)) =20 def out_function(self, fname, name, args): @@ -598,16 +601,16 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - print(f'.TH "{args['function']}" 9 "{args['function']}" "{self.man= _date}" "Kernel Hacker\'s Manual" LINUX') + self.data +=3D f'.TH "{args['function']}" 9 "{args['function']}" "= {self.man_date}" "Kernel Hacker\'s Manual" LINUX' + "\n" =20 - print(".SH NAME") - print(f"{args['function']} \\- {args['purpose']}") + self.data +=3D ".SH NAME\n" + self.data +=3D f"{args['function']} \\- {args['purpose']}\n" =20 - print(".SH SYNOPSIS") + self.data +=3D ".SH SYNOPSIS\n" if args.get('functiontype', ''): - print(f'.B "{args['functiontype']}" {args['function']}') + self.data +=3D f'.B "{args['functiontype']}" {args['function']= }' + "\n" else: - print(f'.B "{args['function']}') + self.data +=3D f'.B "{args['function']}' + "\n" =20 count =3D 0 parenth =3D "(" @@ -620,25 +623,25 @@ class ManFormat(OutputFormat): dtype =3D args['parametertypes'].get(parameter, "") if function_pointer.match(dtype): # Pointer-to-function - print(f'".BI "{parenth}{function_pointer.group(1)}" " ") (= {function_pointer.group(2)}){post}"') + self.data +=3D f'".BI "{parenth}{function_pointer.group(1)= }" " ") ({function_pointer.group(2)}){post}"' + "\n" else: dtype =3D Re(r'([^\*])$').sub(r'\1 ', dtype) =20 - print(f'.BI "{parenth}{dtype}" "{post}"') + self.data +=3D f'.BI "{parenth}{dtype}" "{post}"' + "\n" count +=3D 1 parenth =3D "" =20 if parameterlist: - print(".SH ARGUMENTS") + self.data +=3D ".SH ARGUMENTS\n" =20 for parameter in parameterlist: parameter_name =3D re.sub(r'\[.*', '', parameter) =20 - print(f'.IP "{parameter}" 12') + self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name, "")) =20 for section in sectionlist: - print(f'.SH "{section.upper()}"') + self.data +=3D f'.SH "{section.upper()}"' + "\n" self.output_highlight(sections[section]) =20 def out_enum(self, fname, name, args): @@ -648,33 +651,33 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - print(f'.TH "{args['module']}" 9 "enum {args['enum']}" "{self.man_= date}" "API Manual" LINUX') + self.data +=3D f'.TH "{args['module']}" 9 "enum {args['enum']}" "{= self.man_date}" "API Manual" LINUX' + "\n" =20 - print(".SH NAME") - print(f"enum {args['enum']} \\- {args['purpose']}") + self.data +=3D ".SH NAME\n" + self.data +=3D f"enum {args['enum']} \\- {args['purpose']}\n" =20 - print(".SH SYNOPSIS") - print(f"enum {args['enum']}" + " {") + self.data +=3D ".SH SYNOPSIS\n" + self.data +=3D f"enum {args['enum']}" + " {\n" =20 count =3D 0 for parameter in parameterlist: - print(f'.br\n.BI " {parameter}"') + self.data +=3D f'.br\n.BI " {parameter}"' + "\n" if count =3D=3D len(parameterlist) - 1: - print("\n};") + self.data +=3D "\n};\n" else: - print(", \n.br") + self.data +=3D ", \n.br\n" =20 count +=3D 1 =20 - print(".SH Constants") + self.data +=3D ".SH Constants\n" =20 for parameter in parameterlist: parameter_name =3D Re(r'\[.*').sub('', parameter) - print(f'.IP "{parameter}" 12') + self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(args['parameterdescs'].get(parameter_nam= e, "")) =20 for section in sectionlist: - print(f'.SH "{section}"') + self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections[section]) =20 def out_typedef(self, fname, name, args): @@ -684,13 +687,13 @@ class ManFormat(OutputFormat): sectionlist =3D args.get('sectionlist', []) sections =3D args.get('sections', {}) =20 - print(f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "API Manual= " LINUX') + self.data +=3D f'.TH "{module}" 9 "{typedef}" "{self.man_date}" "A= PI Manual" LINUX' + "\n" =20 - print(".SH NAME") - print(f"typedef {typedef} \\- {purpose}") + self.data +=3D ".SH NAME\n" + self.data +=3D f"typedef {typedef} \\- {purpose}\n" =20 for section in sectionlist: - print(f'.SH "{section}"') + self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections.get(section)) =20 def out_struct(self, fname, name, args): @@ -704,20 +707,20 @@ class ManFormat(OutputFormat): sections =3D args.get('sections', {}) parameterdescs =3D args.get('parameterdescs', {}) =20 - print(f'.TH "{module}" 9 "{struct_type} {struct_name}" "{self.man_= date}" "API Manual" LINUX') + self.data +=3D f'.TH "{module}" 9 "{struct_type} {struct_name}" "{= self.man_date}" "API Manual" LINUX' + "\n" =20 - print(".SH NAME") - print(f"{struct_type} {struct_name} \\- {purpose}") + self.data +=3D ".SH NAME\n" + self.data +=3D f"{struct_type} {struct_name} \\- {purpose}\n" =20 # Replace tabs with two spaces and handle newlines declaration =3D definition.replace("\t", " ") declaration =3D Re(r"\n").sub('"\n.br\n.BI "', declaration) =20 - print(".SH SYNOPSIS") - print(f"{struct_type} {struct_name} " + "{" + "\n.br") - print(f'.BI "{declaration}\n' + "};\n.br\n") + self.data +=3D ".SH SYNOPSIS\n" + self.data +=3D f"{struct_type} {struct_name} " + "{" + "\n.br\n" + self.data +=3D f'.BI "{declaration}\n' + "};\n.br\n\n" =20 - print(".SH Members") + self.data +=3D ".SH Members\n" for parameter in parameterlist: if parameter.startswith("#"): continue @@ -727,9 +730,9 @@ class ManFormat(OutputFormat): if parameterdescs.get(parameter_name) =3D=3D KernelDoc.undescr= ibed: continue =20 - print(f'.IP "{parameter}" 12') + self.data +=3D f'.IP "{parameter}" 12' + "\n" self.output_highlight(parameterdescs.get(parameter_name)) =20 for section in sectionlist: - print(f'.SH "{section}"') + self.data +=3D f'.SH "{section}"' + "\n" self.output_highlight(sections.get(section)) --=20 2.48.1