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