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
--
~Randy
