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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <202507052123.55236.pisa@fel.cvut.cz>
Date: Sat, 5 Jul 2025 21:23:55 +0200
From: Pavel Pisa <pisa@....cvut.cz>
To: Luis Felipe Hernandez <luis.hernandez093@...il.com>
Cc: corbet@....net,
 alexandre.belloni@...tlin.com,
 ondrej.ille@...il.com,
 mkl@...gutronix.de,
 James.Bottomley@...senpartnership.com,
 martin.petersen@...cle.com,
 linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org,
 Ondrej Ille <ondrej.ille@...il.com>,
 Martin Jeřábek <martin.jerabek01@...il.com>,
 Jiří Novák <jnovak@....cvut.cz>
Subject: Re: [PATCH] docs: Fix kernel-doc indentation errors in multiple drivers

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@...il.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@....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