| Message ID | d62f3f3536c0da2062bad87524fb184ad5a9a5f2.1586359676.git.mchehab+huawei@kernel.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation fixes for Kernel 5.8 | expand |
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?
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
On Wed, Apr 08, 2020 at 06:11:54PM +0200, Mauro Carvalho Chehab wrote: > Mark Brown <broonie@kernel.org> escreveu: > > 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. Right, but if the warning is telling us something useful we want to handle it rather than just shutting it up. > 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 OK. Acked-by: Mark Brown <broonie@kernel.org>
Em Wed, 8 Apr 2020 17:16:29 +0100 Mark Brown <broonie@kernel.org> escreveu: > On Wed, Apr 08, 2020 at 06:11:54PM +0200, Mauro Carvalho Chehab wrote: > > Mark Brown <broonie@kernel.org> escreveu: > > > > 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. > > Right, but if the warning is telling us something useful we want to > handle it rather than just shutting it up. True. Without adding the blank line, kernel-doc would output this as: ``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 call spi_finalize_current_transfer() so the subsystem can issue the next transfer. Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the generic subsystem does not call your transfer_one callback. This would be parsed by Sphinx (newer versions) as if the second line: transfer a single spi_transfer. would be a sort of subtitle that should be highlighted with a vertical line before that. E. g. something equivalent to: ============ |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 call spi_finalize_current_transfer() so the subsystem can issue the next transfer. Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the generic subsystem does not call your transfer_one callback. Which is not the desired result. Adding a blank line after it fixes the issue, making it produce the expected output. > > > 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 > > OK. > > Acked-by: Mark Brown <broonie@kernel.org> Thanks, Mauro
diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h index 38286de779e3..aac57b5b7c21 100644 --- a/include/linux/spi/spi.h +++ b/include/linux/spi/spi.h @@ -394,6 +394,7 @@ static inline void spi_unregister_driver(struct spi_driver *sdrv) * for example doing DMA mapping. Called from threaded * context. * @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
We need to add a blank line to avoid this warning: ./include/linux/spi/spi.h:401: WARNING: Unexpected indentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> --- include/linux/spi/spi.h | 1 + 1 file changed, 1 insertion(+)