Re: [PATCH] kernel-doc: add support for handling global variables

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Tue, 9 Sep 2025 17:02:00 -0700
Randy Dunlap <rdunlap@infradead.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@infradead.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@infradead.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.  
> >>>
> >>> 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