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

[Randy Dunlap]

On 11/18/25 1:02 AM, Mauro Carvalho Chehab wrote:
> Em Mon, 17 Nov 2025 22:59:24 -0800
> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx/T/#m947c25d95cb1d96a394410ab1131dc8e9e5013f1
>>> Suggested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
>>> ---
>>>  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);

This var is completely missing in the html output. In the man output,
it is rendered like this:

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

SYNOPSIS
       static DEFINE_MUTEX;

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.


-- 
~Randy