Re: [PATCH] kernel-doc: add support for handling global variables

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed, 10 Sep 2025 12:24:47 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Sun, 07 Sep 2025, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> 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@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)\b\s*(\w*)", cache = False)
> > +doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|global)\b\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