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

[Pavel Pisa <pisa@fel.cvut.cz>]

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