[PATCH] mtd: docg3: fix kernel-doc warnings

[PATCH] mtd: docg3: fix kernel-doc warnings

[Randy Dunlap]

Fix kernel-doc warnings in docg3.h to avoid build warnings and to
improve and documentation:

Warning: ../drivers/mtd/devices/docg3.h:276 bad line:
Warning: drivers/mtd/devices/docg3.h:299 struct member 'max_block' not
 described in 'docg3'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Robert Jarzmik <robert.jarzmik@free.fr>
Cc: Miquel Raynal <miquel.raynal@bootlin.com>
Cc: Richard Weinberger <richard@nod.at>
Cc: Vignesh Raghavendra <vigneshr@ti.com>
Cc: linux-mtd@lists.infradead.org
---
 drivers/mtd/devices/docg3.h |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

--- linux-next-20251114.orig/drivers/mtd/devices/docg3.h
+++ linux-next-20251114/drivers/mtd/devices/docg3.h
@@ -274,11 +274,12 @@ struct docg3_cascade {
  * @cascade: the cascade this device belongs to
  * @device_id: number of the cascaded DoCG3 device (0, 1, 2 or 3)
  * @if_cfg: if true, reads are on 16bits, else reads are on 8bits
-
+ *
  * @reliable: if 0, docg3 in normal mode, if 1 docg3 in fast mode, if 2 in
  *            reliable mode
  *            Fast mode implies more errors than normal mode.
  *            Reliable mode implies that page 2*n and 2*n+1 are clones.
+ * @max_block: maximum block number for this device
  * @bbt: bad block table cache
  * @oob_write_ofs: offset of the MTD where this OOB should belong (ie. in next
  *                 page_write)

______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/

Re: [PATCH] mtd: docg3: fix kernel-doc warnings

[Miquel Raynal]

Hi Randy,

On 15/11/2025 at 23:09:44 -08, Randy Dunlap <rdunlap@infradead.org> wrote:

> Fix kernel-doc warnings in docg3.h to avoid build warnings and to
> improve and documentation:

"to improve and documentation" is incorrect, can you please fix?

> Warning: ../drivers/mtd/devices/docg3.h:276 bad line:
> Warning: drivers/mtd/devices/docg3.h:299 struct member 'max_block' not
>  described in 'docg3'
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Robert Jarzmik <robert.jarzmik@free.fr>
> Cc: Miquel Raynal <miquel.raynal@bootlin.com>
> Cc: Richard Weinberger <richard@nod.at>
> Cc: Vignesh Raghavendra <vigneshr@ti.com>
> Cc: linux-mtd@lists.infradead.org
> ---
>  drivers/mtd/devices/docg3.h |    3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> --- linux-next-20251114.orig/drivers/mtd/devices/docg3.h
> +++ linux-next-20251114/drivers/mtd/devices/docg3.h
> @@ -274,11 +274,12 @@ struct docg3_cascade {
>   * @cascade: the cascade this device belongs to
>   * @device_id: number of the cascaded DoCG3 device (0, 1, 2 or 3)
>   * @if_cfg: if true, reads are on 16bits, else reads are on 8bits
> -
> + *

Wrong fix I believe. What make you think a space is relevant here?

>   * @reliable: if 0, docg3 in normal mode, if 1 docg3 in fast mode, if 2 in
>   *            reliable mode
>   *            Fast mode implies more errors than normal mode.
>   *            Reliable mode implies that page 2*n and 2*n+1 are clones.
> + * @max_block: maximum block number for this device
>   * @bbt: bad block table cache
>   * @oob_write_ofs: offset of the MTD where this OOB should belong (ie. in next
>   *                 page_write)

Thanks,
Miquèl

______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/

Re: [PATCH] mtd: docg3: fix kernel-doc warnings

[Randy Dunlap]

On 11/17/25 12:12 AM, Miquel Raynal wrote:
> Hi Randy,
> 
> On 15/11/2025 at 23:09:44 -08, Randy Dunlap <rdunlap@infradead.org> wrote:
> 
>> Fix kernel-doc warnings in docg3.h to avoid build warnings and to
>> improve and documentation:
> 
> "to improve and documentation" is incorrect, can you please fix?

ugh. Yes, will fix.

>> Warning: ../drivers/mtd/devices/docg3.h:276 bad line:
>> Warning: drivers/mtd/devices/docg3.h:299 struct member 'max_block' not
>>  described in 'docg3'
>>
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> Cc: Robert Jarzmik <robert.jarzmik@free.fr>
>> Cc: Miquel Raynal <miquel.raynal@bootlin.com>
>> Cc: Richard Weinberger <richard@nod.at>
>> Cc: Vignesh Raghavendra <vigneshr@ti.com>
>> Cc: linux-mtd@lists.infradead.org
>> ---
>>  drivers/mtd/devices/docg3.h |    3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> --- linux-next-20251114.orig/drivers/mtd/devices/docg3.h
>> +++ linux-next-20251114/drivers/mtd/devices/docg3.h
>> @@ -274,11 +274,12 @@ struct docg3_cascade {
>>   * @cascade: the cascade this device belongs to
>>   * @device_id: number of the cascaded DoCG3 device (0, 1, 2 or 3)
>>   * @if_cfg: if true, reads are on 16bits, else reads are on 8bits
>> -
>> + *
> 
> Wrong fix I believe. What make you think a space is relevant here?

The '*' is relevant here. A blank line of kernel-doc should have a
beginning asterisk:
 *

>>   * @reliable: if 0, docg3 in normal mode, if 1 docg3 in fast mode, if 2 in
>>   *            reliable mode
>>   *            Fast mode implies more errors than normal mode.
>>   *            Reliable mode implies that page 2*n and 2*n+1 are clones.
>> + * @max_block: maximum block number for this device
>>   * @bbt: bad block table cache
>>   * @oob_write_ofs: offset of the MTD where this OOB should belong (ie. in next
>>   *                 page_write)
> 
> Thanks,
> Miquèl

-- 
~Randy


______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/

Re: [PATCH] mtd: docg3: fix kernel-doc warnings

[Randy Dunlap]

On 11/17/25 11:09 AM, Randy Dunlap wrote:
> 
> 
> On 11/17/25 12:12 AM, Miquel Raynal wrote:
>> Hi Randy,
>>
>> On 15/11/2025 at 23:09:44 -08, Randy Dunlap <rdunlap@infradead.org> wrote:
>>
>>> Fix kernel-doc warnings in docg3.h to avoid build warnings and to
>>> improve and documentation:
>>
>> "to improve and documentation" is incorrect, can you please fix?
> 
> ugh. Yes, will fix.
> 
>>> Warning: ../drivers/mtd/devices/docg3.h:276 bad line:
>>> Warning: drivers/mtd/devices/docg3.h:299 struct member 'max_block' not
>>>  described in 'docg3'
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>> ---
>>> Cc: Robert Jarzmik <robert.jarzmik@free.fr>
>>> Cc: Miquel Raynal <miquel.raynal@bootlin.com>
>>> Cc: Richard Weinberger <richard@nod.at>
>>> Cc: Vignesh Raghavendra <vigneshr@ti.com>
>>> Cc: linux-mtd@lists.infradead.org
>>> ---
>>>  drivers/mtd/devices/docg3.h |    3 ++-
>>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>>
>>> --- linux-next-20251114.orig/drivers/mtd/devices/docg3.h
>>> +++ linux-next-20251114/drivers/mtd/devices/docg3.h
>>> @@ -274,11 +274,12 @@ struct docg3_cascade {
>>>   * @cascade: the cascade this device belongs to
>>>   * @device_id: number of the cascaded DoCG3 device (0, 1, 2 or 3)
>>>   * @if_cfg: if true, reads are on 16bits, else reads are on 8bits
>>> -
>>> + *
>>
>> Wrong fix I believe. What make you think a space is relevant here?
> 
> The '*' is relevant here. A blank line of kernel-doc should have a
> beginning asterisk:
>  *

Ah, I'll just remove the blank line instead. Thanks.

>>>   * @reliable: if 0, docg3 in normal mode, if 1 docg3 in fast mode, if 2 in
>>>   *            reliable mode
>>>   *            Fast mode implies more errors than normal mode.
>>>   *            Reliable mode implies that page 2*n and 2*n+1 are clones.
>>> + * @max_block: maximum block number for this device
>>>   * @bbt: bad block table cache
>>>   * @oob_write_ofs: offset of the MTD where this OOB should belong (ie. in next
>>>   *                 page_write)
>>
>> Thanks,
>> Miquèl
> 

-- 
~Randy


______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/