[21/35] docs: spi: spi.h: fix a doc building warning
diff mbox series

Message ID d62f3f3536c0da2062bad87524fb184ad5a9a5f2.1586359676.git.mchehab+huawei@kernel.org
State New, archived
Headers show
Series
  • Documentation fixes for Kernel 5.8
Related show

Commit Message

Mauro Carvalho Chehab April 8, 2020, 3:46 p.m. UTC
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(+)

Comments

Mark Brown April 8, 2020, 3:49 p.m. UTC | #1
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?
Mauro Carvalho Chehab April 8, 2020, 4:11 p.m. UTC | #2
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
Mark Brown April 8, 2020, 4:16 p.m. UTC | #3
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>
Mauro Carvalho Chehab April 8, 2020, 4:42 p.m. UTC | #4
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

Patch
diff mbox series

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