Message-ID: <c5262290-38e3-4c48-af00-b91f03a065a8@infradead.org>
Date: Tue, 9 Sep 2025 23:13:24 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 Jonathan Corbet <corbet@....net>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] kernel-doc: add support for handling global variables



On 9/9/25 10:59 PM, Randy Dunlap wrote:
> Hi Mauro,
> 
> On 9/9/25 9:23 PM, Mauro Carvalho Chehab wrote:
>> Em Tue, 9 Sep 2025 17:02:00 -0700
>> Randy Dunlap <rdunlap@...radead.org> escreveu:
>>
>>> On 9/9/25 4:50 PM, Randy Dunlap wrote:
>>>>
>>>>
>>>> On 9/9/25 4:49 PM, Randy Dunlap wrote:  
>>>>>
>>>>>
>>>>> On 9/9/25 4:09 PM, Mauro Carvalho Chehab wrote:  
>>>>>> Em Tue, 9 Sep 2025 14:06:43 -0700
>>>>>> Randy Dunlap <rdunlap@...radead.org> escreveu:
>>>>>>  
>>>>>>> On 9/9/25 12:58 PM, Mauro Carvalho Chehab wrote:  
>>>>>>>> Em Tue, 9 Sep 2025 00:27:20 -0700
>>>>>>>> Randy Dunlap <rdunlap@...radead.org> escreveu:  
>>>>>>  
>>>>>>>>> +.. 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.  
>>>>>>



>>>>> Anyway, does this take away something that currently works?  
>>>
>>> The output looks the same with this patch AFAICT.
>>
>> run it in verbose mode to see what command line was passed to
>> the file:
>>
>> 	$ make SPHINXDIRS=your_test_dir V=1 htmldocs
>>
>> This should be printing how the kernel-doc.py command line would be(*):
>>
>> 	scripts/kernel-doc.py -rst -enable-lineno ./include/linux/peci.h
>> 	./include/linux/peci.h:20 Scanning doc for struct peci_controller_ops
>> 	./include/linux/peci.h:32 Scanning doc for struct peci_controller
>> 	./include/linux/peci.h:58 Scanning doc for struct peci_device
>> 	./include/linux/peci.h:88 Scanning doc for struct peci_request
>>
>> (*) the kerneldoc.py extension doesn't call kernel-doc.py, but instead
>>     run directly the Python classes from the library. Yet, to help one
>>     to debug it, the command line is displayed.
> 
> I see. Thanks.
> 
> I get this if I list all of them (on 2 separate identifiers lines):
> 
> ../scripts/kernel-doc.py -rst -enable-lineno -function ROOT_DEV -function system_state -function saved_command_line -function diskseq ../init/kdoc-globals-test.c
> ../init/kdoc-globals-test.c:5 Scanning doc for global ROOT_DEV
> ../init/kdoc-globals-test.c:15 Scanning doc for global system_state
> ../init/kdoc-globals-test.c:27 Scanning doc for global saved_command_line
> ../init/kdoc-globals-test.c:33 Scanning doc for global loops_per_jiffy
> ../init/kdoc-globals-test.c:40 Scanning doc for global preset_lpj
> ../init/kdoc-globals-test.c:49 Scanning doc for global linux_proc_banner
> ../init/kdoc-globals-test.c:63 Scanning doc for global linux_banner
> ../init/kdoc-globals-test.c:72 Scanning doc for global diskseq
> ../init/kdoc-globals-test.c:80 Scanning doc for global rtnl_mutex
> ../scripts/kernel-doc.py -rst -enable-lineno -function loops_per_jiffy -function preset_lpj -function linux_proc_banner -function linux_banner ../init/kdoc-globals-test.c
> 
> or this is I don't use the identifiers line at all:
> 
> ../scripts/kernel-doc.py -rst -enable-lineno ../init/kdoc-globals-test.c
> ../init/kdoc-globals-test.c:5 Scanning doc for global ROOT_DEV
> ../init/kdoc-globals-test.c:15 Scanning doc for global system_state
> ../init/kdoc-globals-test.c:27 Scanning doc for global saved_command_line
> ../init/kdoc-globals-test.c:33 Scanning doc for global loops_per_jiffy
> ../init/kdoc-globals-test.c:40 Scanning doc for global preset_lpj
> ../init/kdoc-globals-test.c:49 Scanning doc for global linux_proc_banner
> ../init/kdoc-globals-test.c:63 Scanning doc for global linux_banner
> ../init/kdoc-globals-test.c:72 Scanning doc for global diskseq
> ../init/kdoc-globals-test.c:80 Scanning doc for global rtnl_mutex
> 
> 
> And then both of them report these warnings (already discussed):
> 
> Documentation/core-api/kernel-api:435: ../init/kdoc-globals-test.c:10: WARNING: Invalid C declaration: Expected end of definition. [error at 32]
>   enum system_states system_state __read_mostly;
>   --------------------------------^
> Documentation/core-api/kernel-api:435: ../init/kdoc-globals-test.c:20: WARNING: Invalid C declaration: Expected end of definition. [error at 25]
>   char *saved_command_line __ro_after_init;
>   -------------------------^
> 
> and the 3 globals with initialization values are skipped/omitted.
> 
> So to get "all identifiers," I should just omit the :identifiers:
> line completely. kernel-doc.rst could use some clarification on that
> point.


Oh darn, the html output is different:

when I omit the :identifiers: line, I see:

Kernel Globals
dev_t ROOT_DEV;
system root device

enum system_states system_state __read_mostly;
system state used during boot or suspend/hibernate/resume

char *saved_command_line __ro_after_init;
kernel’s command line, saved from use at any later time in the kernel.

unsigned long preset_lpj;
lpj (loops per jiffy) value set from kernel command line using “lpj=VALUE”

static atomic64_t diskseq;
unique sequence number for block device instances

and when I list all 8 identifiers (on 2 separate lines), I see:

Kernel Globals
dev_t ROOT_DEV;
system root device

static atomic64_t diskseq;
unique sequence number for block device instances

unsigned long preset_lpj;
lpj (loops per jiffy) value set from kernel command line using “lpj=VALUE”

so for some reason, system_state, saved_command_line, and diskseq are
skipped/omitted when I list all 8 identifiers.


-- 
~Randy

Powered by blists - more mailing lists