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

[Randy Dunlap <rdunlap@infradead.org>]

On 7/5/25 2:36 PM, Randy Dunlap wrote:
> 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
> 
> 

The following patch works for me, both in .c (reading source file)
and the html rendering.

Pavel, feel free to use it.

---
 drivers/net/can/ctucanfd/ctucanfd_base.c |   11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

--- linux-next-20250704.orig/drivers/net/can/ctucanfd/ctucanfd_base.c
+++ linux-next-20250704/drivers/net/can/ctucanfd/ctucanfd_base.c
@@ -506,11 +506,12 @@ static bool ctucan_is_txt_buf_writable(s
  * @buf:	TXT Buffer index to which frame is inserted (0-based)
  * @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
+ * 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
  */
 static bool ctucan_insert_frame(struct ctucan_priv *priv, const struct canfd_frame *cf, u8 buf,
 				bool isfdf)