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.
> >>>
> >>> Hmm.. looking the entire logic:
> >>>
> >>> elif '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)
> >>> else:
> >>> cmd += ['-no-doc-sections']
> >>> self.msg_args["no_doc_sections"] = True
> >>>
> >>> 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"))]
> >>> The right logic should be, instead:
> >>>
> >>> - elif 'identifiers' in self.options:
> >>> - identifiers = self.options.get('identifiers').split()
> >>> - if identifiers:
> >>> - for i in identifiers:
> >>> + elif 'identifiers' in self.options:
> >>> + identifiers = self.options.get('identifiers')
> >>> + if identifiers:
> >>> + for i in identifiers.split():
> >>>
> >>> (tests needed)
> >>
> >> Sheesh, I can't find that code so that I can patch it.
> >> (in today's linux-next 20250909)
> >
> > oops, I was looking in scripts/ and not in Documentation/.
> > got it.
> >
> >> 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.
for instance, on a more complex kernel-doc tags case:
$ make SPHINXDIRS=driver-api/cxl/ V=1 htmldocs 2>&1 |grep scripts/kernel-doc.py
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl pci' ./drivers/cxl/pci.c
scripts/kernel-doc.py -rst -enable-lineno -internal ./drivers/cxl/pci.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl mem' ./drivers/cxl/mem.c
scripts/kernel-doc.py -rst -enable-lineno -internal ./drivers/cxl/cxlmem.h
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/memdev.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl port' ./drivers/cxl/port.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl objects' ./drivers/cxl/cxl.h
scripts/kernel-doc.py -rst -enable-lineno -internal ./drivers/cxl/cxl.h
scripts/kernel-doc.py -rst -enable-lineno -function add_cxl_resources ./drivers/cxl/acpi.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl core hdm' ./drivers/cxl/core/hdm.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/hdm.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/cdat.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl core' ./drivers/cxl/core/port.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/port.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl core pci' ./drivers/cxl/core/pci.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/pci.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl pmem' ./drivers/cxl/core/pmem.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/pmem.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl registers' ./drivers/cxl/core/regs.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/regs.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl mbox' ./drivers/cxl/core/mbox.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/mbox.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl features' ./drivers/cxl/core/features.c
scripts/kernel-doc.py -rst -enable-lineno -function 'cxl core region' ./drivers/cxl/core/region.c
scripts/kernel-doc.py -rst -enable-lineno -no-doc-sections ./drivers/cxl/core/region.c
scripts/kernel-doc.py -rst -enable-lineno -function UAPI ./include/uapi/linux/cxl_mem.h
scripts/kernel-doc.py -rst -enable-lineno -internal ./include/uapi/linux/cxl_mem.h
Thanks,
Mauro
