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@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> escreveu:
>>>>>
>>>>>> 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:
>>>>>
>>>>>>>> +.. 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
