From nobody Tue Sep 9 16:20:59 2025 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 8D5F1283FD4; Sun, 7 Sep 2025 16:22:28 +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=1757262148; cv=none; b=FfV61DUprR/AJTQ/KBmFPyn9MfraMeVRt5xrbjcpSyHbMBPOVRvSh6sm8Lo3AQu62Q2GxqAKwypjQsRkVsp2u8D8Xbts73dEon9rvaSR8fHSIbgh6EijAohQYcPSxW9U7D8mDLqylV+lwBRZaaO8tBFvI7rGCe2Eo+WvCfIIUNQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1757262148; c=relaxed/simple; bh=rseNWx4p8Z6IKHAzzmqFgXVjwzTwBA/0+6t5EuWmh7Q=; h=From:To:Cc:Subject:Date:Message-ID:Content-Type:MIME-Version; b=n/WXoe+yPVCejdPehnDUgfAZdiWCXlxAVaOE/DtKg0nZOHAjQZq7pkF/X/JUK/lGhicizGMFTYFJdtExckZlPk5hHl+kKFyZhx3U9Vm9UfvMgG33T56FfYNKkKxtA8Y3qmdieLW6ebmwy+txtQUT7GZwUvRrq34/FXMlOccd018= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=RRdSjPNf; 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="RRdSjPNf" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 18FF6C4CEF0; Sun, 7 Sep 2025 16:22:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1757262148; bh=rseNWx4p8Z6IKHAzzmqFgXVjwzTwBA/0+6t5EuWmh7Q=; h=From:To:Cc:Subject:Date:From; b=RRdSjPNflz3p8XyQK4Sm6PmaCz5vYZGVnVA5a7Lr3z140VvMEB62b7dshiK09SilK caxoQGIrr8NPbc1L89Cj4XrIdMtXtSWVIm9qBGYlIiSjsm7Ttlc6PCECVo92tTMi/I 85MpYMZvZqvyj13cB2+CY2bK1kcG7xqwjSdnImcJTTjgYcZ2PRLRRPHMWKX5HmH6J0 mmdaHqyE3Uo+lRZnSDeHyXaRW5eyFfRSkagZtyeEbYaJ+7zTo5NyIYDb93uOR9m0Xw k4kiBYBB3aNuqnE1FQINMgdnR9Y4XtcHt4efHtFzfq1EnL2Xtom+U8cGt0v1rWjfHq eSfIhsb/NGemg== Received: from mchehab by mail.kernel.org with local (Exim 4.98.2) (envelope-from ) id 1uvI9p-00000004DP1-22GX; Sun, 07 Sep 2025 18:22:25 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Jonathan Corbet , Mauro Carvalho Chehab , Randy Dunlap , linux-kernel@vger.kernel.org Subject: [PATCH] kernel-doc: add support for handling global variables Date: Sun, 7 Sep 2025 18:22:22 +0200 Message-ID: <80f85eacc306e62de8c9c68712c653ba290c2ff2.1757262141.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.51.0 Content-Type: text/plain; charset="utf-8" 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 Specially on kAPI, sometimes it is desirable to be able to describe global variables that are part of kAPI. Documenting vars with Sphinx is simple, as we don't need to parse a data struct. All we need is the variable declaration and use natice C domain ::c:var: to format it for us. Add support for it. Link: https://lore.kernel.org/linux-doc/491c3022-cef8-4860-a945-c9c4a3b63c0= 9@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 Suggested-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- scripts/lib/kdoc/kdoc_output.py | 31 +++++++++++++++++++++++++++++++ scripts/lib/kdoc/kdoc_parser.py | 25 ++++++++++++++++++++++++- 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/scripts/lib/kdoc/kdoc_output.py b/scripts/lib/kdoc/kdoc_output= .py index 1eca9a918558..405a5c407522 100644 --- a/scripts/lib/kdoc/kdoc_output.py +++ b/scripts/lib/kdoc/kdoc_output.py @@ -199,6 +199,10 @@ class OutputFormat: self.out_enum(fname, name, args) return self.data =20 + if dtype =3D=3D "global": + self.out_global(fname, name, args) + return self.data + if dtype =3D=3D "typedef": self.out_typedef(fname, name, args) return self.data @@ -227,6 +231,9 @@ class OutputFormat: def out_enum(self, fname, name, args): """Outputs an enum""" =20 + def out_global(self, fname, name, args): + """Outputs a global variable""" + def out_typedef(self, fname, name, args): """Outputs a typedef""" =20 @@ -472,6 +479,18 @@ class RestFormat(OutputFormat): self.lineprefix =3D oldprefix self.out_section(args) =20 + def out_global(self, fname, name, args): + oldprefix =3D self.lineprefix + ln =3D args.declaration_start_line + prototype =3D args.other_stuff["var_type"] + + self.data +=3D f" .. c:var:: {prototype} " + + self.print_lineno(ln) + self.lineprefix =3D " " + self.output_highlight(args.get('purpose', '')) + self.data +=3D " " + def out_typedef(self, fname, name, args): =20 oldprefix =3D self.lineprefix @@ -772,6 +791,18 @@ class ManFormat(OutputFormat): self.data +=3D f'.SH "{section}"' + " " self.output_highlight(text) =20 + def out_global(self, fname, name, args): + out_name =3D self.arg_name(args, name) + prototype =3D args.other_stuff["var_type"] + + self.data +=3D f'.TH "{self.modulename}" 9 "{out_name}" "{self.man= _date}" "API Manual" LINUX' + " " + + self.data +=3D ".SH NAME " + self.data +=3D f"{prototype} \- {args['purpose']} " + + self.data +=3D ".SH SYNOPSIS " + self.data +=3D f"enum {name}" + " { " + def out_typedef(self, fname, name, args): module =3D self.modulename purpose =3D args.get('purpose') diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser= .py index 574972e1f741..e2a3f4574894 100644 --- a/scripts/lib/kdoc/kdoc_parser.py +++ b/scripts/lib/kdoc/kdoc_parser.py @@ -64,7 +64,7 @@ type_param =3D KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)= ", cache=3DFalse) # Tests for the beginning of a kerneldoc block in its various forms. # doc_block =3D doc_com + KernRe(r'DOC:\s*(.*)?', cache=3DFalse) -doc_begin_data =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)=08\s*(\w= *)", cache =3D False) +doc_begin_data =3D KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|global)= =08\s*(\w*)", cache =3D False) doc_begin_func =3D KernRe(str(doc_com) + # initial " * ' r"(?:\w+\s*\*\s*)?" + # type (not captured) r'(?:define\s+)?' + # possible "define" (not cap= tured) @@ -886,6 +886,27 @@ class KernelDoc: self.output_declaration('enum', declaration_name, purpose=3Dself.entry.declaration_purpose) =20 + def dump_global(self, ln, proto): + """ + Stores global variables that are part of kAPI. + """ + VAR_ATTRIBS =3D [ + "extern", + ] + OPTIONAL_VAR_ATTR =3D "^(?:" + "|".join(VAR_ATTRIBS) + ")?" + + r=3D KernRe(OPTIONAL_VAR_ATTR + r"(\w.*)\s+([\w_]+)[\d\]\[]*\s*;(?= :#.*)?$") + if not r.match(proto): + self.emit_msg(ln,f"{proto}: can't parse variable") + return + + declaration_name =3D r.group(2) + var_type =3D r.group(0) + + self.output_declaration("global", declaration_name, + var_type=3Dvar_type, + purpose=3Dself.entry.declaration_purpose) + def dump_declaration(self, ln, prototype): """ Stores a data declaration inside self.entries array. @@ -897,6 +918,8 @@ class KernelDoc: self.dump_typedef(ln, prototype) elif self.entry.decl_type in ["union", "struct"]: self.dump_struct(ln, prototype) + elif self.entry.decl_type =3D=3D "global": + self.dump_global(ln, prototype) else: # This would be a bug self.emit_message(ln, f'Unknown declaration type: {self.entry.= decl_type}') --=20 2.51.0