linux-kernel - Re: [PATCH 21/35] docs: spi: spi.h: fix a doc building warning

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200408181154.6c290772@coco.lan>
Date:   Wed, 8 Apr 2020 18:11:54 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Mark Brown <broonie@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        linux-spi@...r.kernel.org
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@...nel.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