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
