Re: [PATCH v3 1/2] kernel-doc: add support for handling global variables

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

Hi Randy,

Em Tue, 18 Nov 2025 21:18:06 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 11/18/25 1:02 AM, Mauro Carvalho Chehab wrote:
> > Em Mon, 17 Nov 2025 22:59:24 -0800
> > Randy Dunlap <rdunlap@infradead.org> escreveu:
> >   
> >> Hi,
> >>
> >> On 11/16/25 3:23 AM, Mauro Carvalho Chehab 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.
> >>>
> >>> 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 | 45 ++++++++++++++++++++++++++
> >>>  scripts/lib/kdoc/kdoc_parser.py | 56 ++++++++++++++++++++++++++++++++-
> >>>  2 files changed, 100 insertions(+), 1 deletion(-)    
> >>
> >> Thanks for the update. It's looking much better.  
> > 
> > Great!
> >   
> >> I have a few comments/questions, all about typedefs.  
> >   
> 
> Hi Mauro,
> 
> I just noticed that in my sample init/kdoc-globals-test.c file
> (I have s/global/var/ in it), there is one global var that is missing
> or misparsed:
> 
> // from net/core/rtnetlink.c:
> /**
>  * var rtnl_mutex - historical global lock for networking control operations.
>  *
>  * @rtnl_mutex is used to serialize rtnetlink requests
>  * and protect all kernel internal data structures related to networking.
>  *
>  * See Documentation/networking/netdevices.rst for details.
>  * Often known as the rtnl_lock, although rtnl_lock is a kernel function.
>  */
> static DEFINE_MUTEX(rtnl_mutex);

Just like we have it for functions, we'll need special regex when
macros are in use.

I guess we can have a generic one to cover multiple defines, like:

	DEFINE_\w+\((\w+)\)

This should be enough to pick the name of the var. We might try
a more generic approach that would be expecting:

	<some macro>(<name>)

but IMHO this could be harder to maintain in long term.

> This var is completely missing in the html output.

Now, even if we pick it correctly, Sphinx C domain is not enough for
things like this, e.g.:

+        self.data += f"\n\n.. c:var:: {prototype}\n\n"

will fail if prototype is "DEFINE_MUTEX(rtnl_mutex)", as c:var::
will try to parse it without using macros.

See:
	https://www.sphinx-doc.org/en/master/usage/domains/c.html
	
On such case, we'll likely need to use:

	.. c:macro:: {name}

To generate the cross reference and then output the prototype or
":c:type:", which is what we use on several places where the C domain
parser won't work.

Maybe an alternate would be to use:

	.. c:macro:: name(arg list)

But it may be hard to see that this is a variable and not a macro
declaration.

Hmm... looking at https://www.sphinx-doc.org/en/master/usage/domains/c.html#directive-c-alias
it seems that Sphinx 3.2 and above introduced "c:alias:". Maybe it might
be helpful. 

> In the man output,
> it is rendered like this:

On man output, we don't need cross-references, so, we can change the
logic to output the full prototype before being parsed.

> 
> NAME
>        static DEFINE_MUTEX - historical global lock for networking control  op‐
>        erations.

Once we get the name properly parsed, this should be easy to fix.

> 
> SYNOPSIS
>        static DEFINE_MUTEX;

Yeah, it would need some tweaks for the macro case. Synopsis should be
easy to fix: instead of {prototype}, we can use {full_proto}, which is
also at the dict.

> 
> Description
>        rtnl_mutex  is used to serialize rtnetlink requests and protect all ker‐
>        nel internal data structures  related  to  networking.   See  Documenta‐
>        tion/networking/netdevices.rst   for   details.    Often  known  as  the
>        rtnl_lock, although rtnl_lock is a kernel function.
> 
> 



Thanks,
Mauro