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@xxxxxxxxx>
>>> ---
>>> 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)
