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

[Randy Dunlap]

On 9/9/25 12:58 PM, Mauro Carvalho Chehab wrote:
> Em Tue, 9 Sep 2025 00:27:20 -0700
> Randy Dunlap <rdunlap@xxxxxxxxxxxxx> escreveu:
> 
>> Hi Mauro,
>>


>> So, I grabbed some global data from 6-8 places in the kernel and put them intoinit/kdoc-globals-test.c. Then I modified Documentation/core-api/kernel-api.rst
>> like this at the end of that file:
>>
>> +
>> +Kernel Globals
>> +==========================
>> +
>> +.. kernel-doc:: init/kdoc-globals-test.c
>> +   :identifiers:
>>
>> The html output says
>> "Kernel Globals"
>> but nothing else.
> 
> I usually don't add :identifiers: on kernel-doc entries. If you use
> identifiers, you need to explicitly tell what symbols you want.

Well, it worked/works without using having any identifiers listed, and
the docs in Documentation/doc-guide/kernel-doc.rst says that they are
optional:

identifiers: *[ function/type ...]*
  Include documentation for each *function* and *type* in *source*.
  If no *function* is specified, the documentation for all functions
  and types in the *source* will be included.
  *type* can be a struct, union, enum, or typedef identifier.


> As a reference, kerneldoc.py logic for identifiers is:
> 
> 	if 'identifiers' in self.options:                                                                                                                                                                      
>             identifiers = self.options.get('identifiers').split()                                                                                                                                                
>             if identifiers:
>                 for i in identifiers:
>                     i = i.rstrip("\\").strip()
>                     if not i:
>                         continue
> 
>                     cmd += ['-function', i]
>                     self.msg_args["symbol"].append(i)
> 
> without it, it will pick the entire set of symbols. 

Yeah, that's exactly what I want, so I don't see a problem.


>> My test files are attached. I dumbed down (simplified) a few
>> of the globals from fancy types to just unsigned long, but that
>> didn't help the output results any.
> 
> Looking on your attachment, you can either drop :identifiers:
> or list all of them:
> 
> 	.. kernel-doc:: init/kdoc-globals-test.c
> 	   :identifiers: ROOT_DEV loop_per_jiffy
> 	   :identifiers: preset_lpj
> 
> (here, it should only show those 3 symbols)
> 
> see, having this:
> 
> 	.. kernel-doc:: init/kdoc-globals-test.c
> 	   :identifiers: ROOT_DEV 
> 
> will run:
> 
> 	$ ./scripts/kernel-doc init/kdoc-globals-test.c -function ROOT_DEV 
> 
> 
> 	.. c:var:: unsigned long ROOT_DEV;
> 
> 	  system root device


Yes, I understand how to use explicit identifiers.  :)
Thanks.
-- 
~Randy