Re: [PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings

From: Boris Brezillon <boris.brezillon@free-electrons.com>
To: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Cc: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	Jonathan Corbet <corbet@lwn.net>,
	Richard Weinberger <richard@nod.at>,
	linux-kernel@vger.kernel.org,
	Mauro Carvalho Chehab <mchehab@infradead.org>,
	Marek Vasut <marek.vasut@gmail.com>,
	linux-mtd@lists.infradead.org,
	Cyrille Pitchen <cyrille.pitchen@atmel.com>,
	Brian Norris <computersforpeace@gmail.com>,
	David Woodhouse <dwmw2@infradead.org>
Subject: Re: [PATCH v2 39/53] mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
Date: Tue, 16 May 2017 15:13:24 +0200	[thread overview]
Message-ID: <20170516151324.22afa72a@bbrezillon> (raw)
In-Reply-To: <b6f6c29454d236e85f2912cb0f9366825ca1b0be.1494935649.git.mchehab@s-opensource.com>

On Tue, 16 May 2017 09:16:31 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> ./drivers/mtd/nand/nand_bbt.c:1: warning: no structured comments found
> ./include/linux/mtd/nand.h:785: ERROR: Unexpected indentation.
> ./drivers/mtd/nand/nand_base.c:449: WARNING: Definition list ends without a blank line; unexpected unindent.
> ./drivers/mtd/nand/nand_base.c:1161: ERROR: Unexpected indentation.
> ./drivers/mtd/nand/nand_base.c:1162: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Acked-by: Boris Brezillon <boris.brezillon@free-electrons.com>

> ---
>  Documentation/driver-api/mtdnand.rst | 3 ---
>  drivers/mtd/nand/nand_base.c         | 7 +++++--
>  include/linux/mtd/nand.h             | 2 +-
>  3 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/driver-api/mtdnand.rst b/Documentation/driver-api/mtdnand.rst
> index 7c19795ebb4a..e9afa586d15e 100644
> --- a/Documentation/driver-api/mtdnand.rst
> +++ b/Documentation/driver-api/mtdnand.rst
> @@ -970,9 +970,6 @@ hints" for an explanation.
>  .. kernel-doc:: drivers/mtd/nand/nand_base.c
>     :export:
>  
> -.. kernel-doc:: drivers/mtd/nand/nand_bbt.c
> -   :export:
> -
>  .. kernel-doc:: drivers/mtd/nand/nand_ecc.c
>     :export:
>  
> diff --git a/drivers/mtd/nand/nand_base.c b/drivers/mtd/nand/nand_base.c
> index b0524f8accb6..c8988c01e0d7 100644
> --- a/drivers/mtd/nand/nand_base.c
> +++ b/drivers/mtd/nand/nand_base.c
> @@ -442,10 +442,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
>   * specify how to write bad block markers to OOB (chip->block_markbad).
>   *
>   * We try operations in the following order:
> + *
>   *  (1) erase the affected block, to allow OOB marker to be written cleanly
>   *  (2) write bad block marker to OOB area of affected block (unless flag
>   *      NAND_BBT_NO_OOB_BBM is present)
>   *  (3) update the BBT
> + *
>   * Note that we retain the first error encountered in (2) or (3), finish the
>   * procedures, and dump the error in the end.
>  */
> @@ -1155,9 +1157,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
>   * @mtd: mtd info
>   * @ofs: offset to start unlock from
>   * @len: length to unlock
> - * @invert: when = 0, unlock the range of blocks within the lower and
> + * @invert:
> + *        - when = 0, unlock the range of blocks within the lower and
>   *                    upper boundary address
> - *          when = 1, unlock the range of blocks outside the boundaries
> + *        - when = 1, unlock the range of blocks outside the boundaries
>   *                    of the lower and upper boundary address
>   *
>   * Returs unlock status.
> diff --git a/include/linux/mtd/nand.h b/include/linux/mtd/nand.h
> index 9591e0fbe5bd..3d5b20379ba3 100644
> --- a/include/linux/mtd/nand.h
> +++ b/include/linux/mtd/nand.h
> @@ -779,7 +779,7 @@ nand_get_sdr_timings(const struct nand_data_interface *conf)
>   *			Minimum amount of bit errors per @ecc_step_ds guaranteed
>   *			to be correctable. If unknown, set to zero.
>   * @ecc_step_ds:	[INTERN] ECC step required by the @ecc_strength_ds,
> - *                      also from the datasheet. It is the recommended ECC step
> + *			also from the datasheet. It is the recommended ECC step
>   *			size, if known; if unknown, set to zero.
>   * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
>   *			      set to the actually used ONFI mode if the chip is