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

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

[Luis Felipe Hernandez]

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/i3c/device.c b/drivers/i3c/device.c
index e80e48756914..7aec9c1e01b9 100644
--- a/drivers/i3c/device.c
+++ b/drivers/i3c/device.c
@@ -28,9 +28,9 @@
  *
  * Return: 0 in case of success, a negative error core otherwise.
  *	   -EAGAIN: controller lost address arbitration. Target
- *		    (IBI, HJ or controller role request) win the bus. Client
- *		    driver needs to resend the 'xfers' some time later.
- *		    See I3C spec ver 1.1.1 09-Jun-2021. Section: 5.1.2.2.3.
+ *	   (IBI, HJ or controller role request) win the bus. Client
+ *	   driver needs to resend the 'xfers' some time later.
+ *	   See I3C spec ver 1.1.1 09-Jun-2021. Section: 5.1.2.2.3.
  */
 int i3c_device_do_priv_xfers(struct i3c_device *dev,
 			     struct i3c_priv_xfer *xfers,
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)
diff --git a/drivers/scsi/scsi.c b/drivers/scsi/scsi.c
index 534310224e8f..5f46f593d44f 100644
--- a/drivers/scsi/scsi.c
+++ b/drivers/scsi/scsi.c
@@ -243,8 +243,8 @@ EXPORT_SYMBOL(scsi_change_queue_depth);
  * 		need to adjust the queue depth on the device.
  *
  * Returns:	0 - No change needed, >0 - Adjust queue depth to this new depth,
- * 		-1 - Drop back to untagged operation using host->cmd_per_lun
- * 			as the untagged command depth
+ *              -1 - Drop back to untagged operation using host->cmd_per_lun
+ *              as the untagged command depth
  *
  * Lock Status:	None held on entry
  *
-- 
2.50.0

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

[Pavel Pisa]

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

 * 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

Best wishes,

                Pavel

                Pavel Pisa
    phone:      +420 603531357
    e-mail:     pisa@cmp.felk.cvut.cz
    Department of Control Engineering FEE CVUT
    Karlovo namesti 13, 121 35, Prague 2
    university: http://control.fel.cvut.cz/
    personal:   http://cmp.felk.cvut.cz/~pisa
    social:     https://social.kernel.org/ppisa
    projects:   https://www.openhub.net/accounts/ppisa
    CAN related:http://canbus.pages.fel.cvut.cz/
    RISC-V education: https://comparch.edu.cvut.cz/
    Open Technologies Research Education and Exchange Services
    https://gitlab.fel.cvut.cz/otrees/org/-/wikis/home

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

[Randy Dunlap]

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

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

[Randy Dunlap]

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)

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 761 bytes --]

On Sat, Jul 05, 2025 at 02:36:45PM -0700, Randy Dunlap wrote:
> 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.
> 
 
I think Sphinx reported these warnings on docs-next tree.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Randy Dunlap]

On 7/6/25 5:37 PM, Bagas Sanjaya wrote:
> On Sat, Jul 05, 2025 at 02:36:45PM -0700, Randy Dunlap wrote:
>> 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.
>>
>  
> I think Sphinx reported these warnings on docs-next tree.
> 
> Thanks.
> 

I would hope and think that the docs-next tree is in linux-next and I
tested on linux-next.

But I probably don't know what is going on...

-- 
~Randy

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

[Felipe Hernandez]

On Sun, Jul 6, 2025 at 8:37 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On Sat, Jul 05, 2025 at 02:36:45PM -0700, Randy Dunlap wrote:
> > 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.
> >
>
> I think Sphinx reported these warnings on docs-next tree.
>
> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara

Hi,

I just wanted to follow up with the thread. I had inadvertently done a
reply not reply all after the first series of feedback from Pavel and
Randy. I agree with Randy in that the nested lists be updated to use
ReST list syntax. I'm working on a v2 and spot checking the output.

For reference:
I am running docutils (Docutils 0.21.2, Python 3.13.5, on linux)
My branch was based on commit 50c8770a42faf8b1c7abe93e7c114337f580a97d
(linux-next/master).
The specific error(s):
/home/linux/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver:526:
./drivers/net/can/ctucanfd/ctucanfd_base.c:511: ERROR: Unexpected
indentation. [docutils]

I apologize if I should've started this work using the docs-next tree.
I wasn't aware of it at the moment and was utilizing linux-next.

Best,

Felipe

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 682 bytes --]

On Sat, Jul 05, 2025 at 02:45:47PM -0700, Randy Dunlap wrote:
> - * 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

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Randy Dunlap]

Hi Felipe,

On 7/7/25 6:43 AM, Felipe Hernandez wrote:
> On Sun, Jul 6, 2025 at 8:37 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>>
>> On Sat, Jul 05, 2025 at 02:36:45PM -0700, Randy Dunlap wrote:
>>> 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.
>>>
>>
>> I think Sphinx reported these warnings on docs-next tree.

They are actually docutils warnings. and I do see them now,
I had just overlooked them.

> 
> Hi,
> 
> I just wanted to follow up with the thread. I had inadvertently done a
> reply not reply all after the first series of feedback from Pavel and
> Randy. I agree with Randy in that the nested lists be updated to use
> ReST list syntax. I'm working on a v2 and spot checking the output.
> 
> For reference:
> I am running docutils (Docutils 0.21.2, Python 3.13.5, on linux)
> My branch was based on commit 50c8770a42faf8b1c7abe93e7c114337f580a97d
> (linux-next/master).
> The specific error(s):
> /home/linux/Documentation/networking/device_drivers/can/ctu/ctucanfd-driver:526:
> ./drivers/net/can/ctucanfd/ctucanfd_base.c:511: ERROR: Unexpected
> indentation. [docutils]
> 
> I apologize if I should've started this work using the docs-next tree.
> I wasn't aware of it at the moment and was utilizing linux-next.

The linux-next tree has these warnings in it. I often use it for patches.

Have you made a new version of the patch? I haven't seen it.

Thanks.
-- 
~Randy