Em Wed, 10 Sep 2025 12:24:47 +0300 Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu: > On Sun, 07 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> wrote: > > 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. > > Bikeshedding on "global", it sort of implies visibility or linkage, but > here it means "variable". > > You could document variables that are static, global to the module, or > exported to the entire kernel. And you could document functions that are > global (for some meaning of global). > > I didn't look into kernel-doc, but can't you figure the type out from > the source, instead of having to tell it? And if you can't, why not just > make it "var" (matching Sphinx) or "variable"? I don't have a strong opinion here. I ended picking "global" just as a sort of declaration of intent, in the sense that this is aimed to be used for kAPI vars. Now, "var" has certainly an appeal, as it matches Sphinx. > > > BR, > Jani. > > > > > Link: https://lore.kernel.org/linux-doc/491c3022-cef8-4860-a945-c9c4a3b63c09@xxxxxxxxxxxxx/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 > > Suggested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> > > --- > > 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
