Re: [PATCH] docs: Fix kernel-doc indentation errors in multiple drivers

[Randy Dunlap <rdunlap@infradead.org>]

Hi,


On 7/5/25 12:23 PM, Pavel Pisa wrote:
> Dear Luis Felipe Hernandez,
> 
> I focus only on drivers/net/can/ctucanfd/ctucanfd_base.c
> 
> On Thursday 03 of July 2025 04:35:11 Luis Felipe Hernandez wrote:
>> Fix kernel-doc formatting issues causing "Unexpected indentation"
>> errors during documentation build in CAN, SCSI, and I3C drivers.
>>
>> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
>> ---
>>  drivers/i3c/device.c                     | 6 +++---
>>  drivers/net/can/ctucanfd/ctucanfd_base.c | 8 ++++----
>>  drivers/scsi/scsi.c                      | 4 ++--
>>  3 files changed, 9 insertions(+), 9 deletions(-)
>>
> ...
>> diff --git a/drivers/net/can/ctucanfd/ctucanfd_base.c
>> b/drivers/net/can/ctucanfd/ctucanfd_base.c index bf6398772960..bd6938f6e105
>> 100644
>> --- a/drivers/net/can/ctucanfd/ctucanfd_base.c
>> +++ b/drivers/net/can/ctucanfd/ctucanfd_base.c
>> @@ -507,10 +507,10 @@ static bool ctucan_is_txt_buf_writable(struct
>> ctucan_priv *priv, u8 buf) * @isfdf:	True - CAN FD Frame, False - CAN 2.0
>> Frame
>>   *
>>   * Return: True - Frame inserted successfully
>> - *	   False - Frame was not inserted due to one of:
>> - *			1. TXT Buffer is not writable (it is in wrong state)
>> - *			2. Invalid TXT buffer index
>> - *			3. Invalid frame length
>> + *         False - Frame was not inserted due to one of:
>> + *         1. TXT Buffer is not writable (it is in wrong state)
>> + *         2. Invalid TXT buffer index
>> + *         3. Invalid frame length
>>   */
>>  static bool ctucan_insert_frame(struct ctucan_priv *priv, const struct
>> canfd_frame *cf, u8 buf, bool isfdf)
> 
> I do not have strong opinion there but the numberred list {1., 2., 3.}
> is the sublevel of the top list {True, False} under the False option.
> 
> You have flattened the list which hides the connection of error
> reasons to the False return value.
> 
> But if the strict rules for indentation are more important
> than my feeling for easy navigation then I do not want to stand
> in way and go forward.
> 
> Aligning False under True has some reason, the original
> text used tabs for indentnation, which is I understand
> as generally preferred in kernel sources and the original
> comment with correct tab = 8 spaces renders well for me

I don't see any need for the tab->spaces conversion either.

It renders in .c (text) or html?  It looks fine in the .c source
file, but the current html rendering is like this:

Return

True - Frame inserted successfully False - Frame was not inserted due to one of:

	1. TXT Buffer is not writable (it is in wrong state)
	2. Invalid TXT buffer index
	3. Invalid frame length

It needs something to turn True and False into a bullet list
(non-numbered), as documented in Documentation/doc-guide/kernel-doc.rst:

     So, in order to produce the desired line breaks, you need to use a
     ReST list, e. g.::

      * Return:
      * * %0		- OK to runtime suspend the device
      * * %-EBUSY	- Device should not be runtime suspended



I don't see any of these kernel-doc warnings. I would guess that
either Pavel or I am using some older/newer version of whatever
software is causing this.

> 
>  * Return: True - Frame inserted successfully
>  *	   False - Frame was not inserted due to one of:
>  *			1. TXT Buffer is not writable (it is in wrong state)
>  *			2. Invalid TXT buffer index
>  *			3. Invalid frame length


-- 
~Randy