Em Sun, 7 Sep 2025 18:22:22 +0200 Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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@xxxxxxxxxxxxx/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1 > Suggested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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
