scripts/lib/kdoc/kdoc_output.py | 31 +++++++++++++++++++++++++++++++ scripts/lib/kdoc/kdoc_parser.py | 25 ++++++++++++++++++++++++- 2 files changed, 55 insertions(+), 1 deletion(-)
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-c9c4a3b63c09@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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
+ if dtype == "global":
+ self.out_global(fname, name, args)
+ return self.data
+
if dtype == "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"""
+ def out_global(self, fname, name, args):
+ """Outputs a global variable"""
+
def out_typedef(self, fname, name, args):
"""Outputs a typedef"""
@@ -472,6 +479,18 @@ class RestFormat(OutputFormat):
self.lineprefix = oldprefix
self.out_section(args)
+ def out_global(self, fname, name, args):
+ oldprefix = self.lineprefix
+ ln = args.declaration_start_line
+ prototype = args.other_stuff["var_type"]
+
+ self.data += f"
.. c:var:: {prototype}
"
+
+ self.print_lineno(ln)
+ self.lineprefix = " "
+ self.output_highlight(args.get('purpose', ''))
+ self.data += "
"
+
def out_typedef(self, fname, name, args):
oldprefix = self.lineprefix
@@ -772,6 +791,18 @@ class ManFormat(OutputFormat):
self.data += f'.SH "{section}"' + "
"
self.output_highlight(text)
+ def out_global(self, fname, name, args):
+ out_name = self.arg_name(args, name)
+ prototype = args.other_stuff["var_type"]
+
+ self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "
"
+
+ self.data += ".SH NAME
"
+ self.data += f"{prototype} \- {args['purpose']}
"
+
+ self.data += ".SH SYNOPSIS
"
+ self.data += f"enum {name}" + " {
"
+
def out_typedef(self, fname, name, args):
module = self.modulename
purpose = 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 = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
# Tests for the beginning of a kerneldoc block in its various forms.
#
doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False)
-doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\s*(\w*)", cache = False)
+doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|global)\s*(\w*)", cache = False)
doc_begin_func = KernRe(str(doc_com) + # initial " * '
r"(?:\w+\s*\*\s*)?" + # type (not captured)
r'(?:define\s+)?' + # possible "define" (not captured)
@@ -886,6 +886,27 @@ class KernelDoc:
self.output_declaration('enum', declaration_name,
purpose=self.entry.declaration_purpose)
+ def dump_global(self, ln, proto):
+ """
+ Stores global variables that are part of kAPI.
+ """
+ VAR_ATTRIBS = [
+ "extern",
+ ]
+ OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?"
+
+ r= 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 = r.group(2)
+ var_type = r.group(0)
+
+ self.output_declaration("global", declaration_name,
+ var_type=var_type,
+ purpose=self.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 == "global":
+ self.dump_global(ln, prototype)
else:
# This would be a bug
self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
--
2.51.0Em Sun, 7 Sep 2025 18:22:22 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
> 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-c9c4a3b63c09@infradead.org/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1
> Suggested-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Btw, this is still at RFC level, as, for the final version we need:
- to document this new kernel-doc feature;
- to suppress (or keep) the end ";";
- do some cleanups/improvements at the regex to ensure that it is generic
enough. For instance, the way it was defineded, it doesn't handle yet
variables with assigned values like:
extern int foo = 5;
- if it has a default non-zero value, should it be documented or not,
and, if so, how;
- to decide if we add "extern" to all outputs, to none of them or if we
just follow what is at the documented declaration (the current
implementation does the latter;
- to decide weather use "global"/"var" or something else.
Also, it would be interesting to have a real case where we want
to document kAPI variables.
Randy,
if you have some real case examples, perhaps you could pick this patch
and add on a patch series after taking the above into consideration.
> ---
> 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
>
> + if dtype == "global":
> + self.out_global(fname, name, args)
> + return self.data
> +
> if dtype == "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"""
>
> + def out_global(self, fname, name, args):
> + """Outputs a global variable"""
> +
> def out_typedef(self, fname, name, args):
> """Outputs a typedef"""
>
> @@ -472,6 +479,18 @@ class RestFormat(OutputFormat):
> self.lineprefix = oldprefix
> self.out_section(args)
>
> + def out_global(self, fname, name, args):
> + oldprefix = self.lineprefix
> + ln = args.declaration_start_line
> + prototype = args.other_stuff["var_type"]
> +
> + self.data += f"
>
> .. c:var:: {prototype}
>
> "
> +
> + self.print_lineno(ln)
> + self.lineprefix = " "
> + self.output_highlight(args.get('purpose', ''))
> + self.data += "
> "
> +
> def out_typedef(self, fname, name, args):
>
> oldprefix = self.lineprefix
> @@ -772,6 +791,18 @@ class ManFormat(OutputFormat):
> self.data += f'.SH "{section}"' + "
> "
> self.output_highlight(text)
>
> + def out_global(self, fname, name, args):
> + out_name = self.arg_name(args, name)
> + prototype = args.other_stuff["var_type"]
> +
> + self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "
> "
> +
> + self.data += ".SH NAME
> "
> + self.data += f"{prototype} \- {args['purpose']}
> "
> +
> + self.data += ".SH SYNOPSIS
> "
> + self.data += f"enum {name}" + " {
> "
> +
> def out_typedef(self, fname, name, args):
> module = self.modulename
> purpose = 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 = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False)
> # Tests for the beginning of a kerneldoc block in its various forms.
> #
> doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False)
> -doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\s*(\w*)", cache = False)
> +doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|global)\s*(\w*)", cache = False)
> doc_begin_func = KernRe(str(doc_com) + # initial " * '
> r"(?:\w+\s*\*\s*)?" + # type (not captured)
> r'(?:define\s+)?' + # possible "define" (not captured)
> @@ -886,6 +886,27 @@ class KernelDoc:
> self.output_declaration('enum', declaration_name,
> purpose=self.entry.declaration_purpose)
>
> + def dump_global(self, ln, proto):
> + """
> + Stores global variables that are part of kAPI.
> + """
> + VAR_ATTRIBS = [
> + "extern",
> + ]
> + OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?"
> +
> + r= 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 = r.group(2)
> + var_type = r.group(0)
> +
> + self.output_declaration("global", declaration_name,
> + var_type=var_type,
> + purpose=self.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 == "global":
> + self.dump_global(ln, prototype)
> else:
> # This would be a bug
> self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')
Thanks,
Mauro
© 2016 - 2025 Red Hat, Inc.