Messages in this thread | | | Date | Wed, 8 Apr 2020 18:11:54 +0200 | From | Mauro Carvalho Chehab <> | Subject | Re: [PATCH 21/35] docs: spi: spi.h: fix a doc building warning |
| |
Hi Mark,
Em Wed, 8 Apr 2020 16:49:25 +0100 Mark Brown <broonie@kernel.org> escreveu:
> On Wed, Apr 08, 2020 at 05:46:13PM +0200, Mauro Carvalho Chehab wrote: > > We need to add a blank line to avoid this warning: > > > > ./include/linux/spi/spi.h:401: WARNING: Unexpected indentation. > > > * @transfer_one: transfer a single spi_transfer. > > + * > > * - return 0 if the transfer is finished, > > * - return 1 if the transfer is still in progress. When > > * the driver is finished with this transfer it must > > Are you sure this is a sensible fix? The following lines should be part > of the documentation for transfer_one, will that be the case after your > change?
Without that, Sphinx will warn and may produce something unexpected.
Yet, right now, kernel-doc is not prepared for the above change. When kernel-doc finds a blank line, it just assumes that the remaining content is part of the description. That is due to some laziness on its parser.
This is fixed by patch 20/35 on this series:
Subject: [PATCH 20/35] docs: scripts/kernel-doc: accept blank lines on parameter description
If this patch is applied after 20/25, the output should produce the correct result:
https://www.infradead.org/~mchehab/kernel_docs/driver-api/spi.html#spi-master-methods
Thanks, Mauro
| |