Message-ID: <14133b75-a984-4244-a18d-f02f0b81d1b7@infradead.org>
Date: Tue, 9 Sep 2025 22:59:41 -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

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.  
>>>>>


>>>>> I suspect that an empty identifier could be raising an exception.  
>>
>> and it's being caught and ignored (not printed)?
> 
> there is a try/except block to capture exceptions. It is supposed to
> print something, though:
> 
>         try:
>             if kfiles:
>                 return self.run_kdoc(cmd, kfiles)
>             else:
>                 return self.run_cmd(cmd)
> 
>         except Exception as e:  # pylint: disable=W0703
>             logger.warning("kernel-doc '%s' processing failed with: %s" %
>                            (cmd_str(cmd), pformat(e)))
>             return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
> 


>>>> 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.

Thanks.
-- 
~Randy

Powered by blists - more mailing lists