[PATCH v3] docs: Fix kernel-doc error in CAN driver

[PATCH v3] docs: Fix kernel-doc error in CAN driver

[Luis Felipe Hernandez]

Fix kernel-doc formatting issue causing unexpected indentation error
in ctucanfd driver documentation build. Convert main return values
to bullet list format while preserving numbered sub-list in order to
correct indentation error and visual structure in rendered html.

Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>

---
Changes since v2:
- Focus only on CAN driver (GPU and I3C already fixed by Bagas Sanjaya)
- Remove blank line that caused unwanted 'Description' output
- Keep numbered sub-list format as suggested by Randy Dunlap
- Move changelog after cutter as suggested by Vincent Mailhol

Link(v2): https://lore.kernel.org/all/20250720152401.70720-1-luis.hernandez093@gmail.com/
Link(v1): https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/
---
 drivers/net/can/ctucanfd/ctucanfd_base.c | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/drivers/net/can/ctucanfd/ctucanfd_base.c b/drivers/net/can/ctucanfd/ctucanfd_base.c
index bf6398772960..8bd3f0fc385c 100644
--- a/drivers/net/can/ctucanfd/ctucanfd_base.c
+++ b/drivers/net/can/ctucanfd/ctucanfd_base.c
@@ -506,11 +506,12 @@ static bool ctucan_is_txt_buf_writable(struct ctucan_priv *priv, u8 buf)
  * @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)
-- 
2.43.0

Re: [PATCH v3] docs: Fix kernel-doc error in CAN driver

[Vincent Mailhol]

On 22/07/2025 at 12:53, Luis Felipe Hernandez wrote:
> Fix kernel-doc formatting issue causing unexpected indentation error
> in ctucanfd driver documentation build. Convert main return values
> to bullet list format while preserving numbered sub-list in order to
> correct indentation error and visual structure in rendered html.
> 
> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>

Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>


Yours sincerely,
Vincent Mailhol

Re: [PATCH v3] docs: Fix kernel-doc error in CAN driver

[Pavel Pisa]

On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
> On 22/07/2025 at 12:53, Luis Felipe Hernandez wrote:
> > Fix kernel-doc formatting issue causing unexpected indentation error
> > in ctucanfd driver documentation build. Convert main return values
> > to bullet list format while preserving numbered sub-list in order to
> > correct indentation error and visual structure in rendered html.
> >
> > Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
>
> Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>

Reviewed-by: Vincent Mailhol <pisa@fel.cvut.cz>

This version keeps readability in the plain source.

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 v3] docs: Fix kernel-doc error in CAN driver

[Vincent Mailhol]

On 22/07/2025 at 15:37, Pavel Pisa wrote:
> On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
>> On 22/07/2025 at 12:53, Luis Felipe Hernandez wrote:
>>> Fix kernel-doc formatting issue causing unexpected indentation error
>>> in ctucanfd driver documentation build. Convert main return values
>>> to bullet list format while preserving numbered sub-list in order to
>>> correct indentation error and visual structure in rendered html.
>>>
>>> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
>>
>> Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>
> 
> Reviewed-by: Vincent Mailhol <pisa@fel.cvut.cz>
               ^^^^^^^^^^^^^^^
Are you trying to impersonate me?

Can you reply again with the proper Reviewed-by tag? ;)


Yours sincerely,
Vincent Mailhol

Re: [PATCH v3] docs: Fix kernel-doc error in CAN driver

[Pavel Pisa]

On Tuesday 22 of July 2025 09:27:39 Vincent Mailhol wrote:
> On 22/07/2025 at 15:37, Pavel Pisa wrote:
> > On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
> >> On 22/07/2025 at 12:53, Luis Felipe Hernandez wrote:
> >>> Fix kernel-doc formatting issue causing unexpected indentation error
> >>> in ctucanfd driver documentation build. Convert main return values
> >>> to bullet list format while preserving numbered sub-list in order to
> >>> correct indentation error and visual structure in rendered html.
> >>>
> >>> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> >>
> >> Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>
> >
> > Reviewed-by: Vincent Mailhol <pisa@fel.cvut.cz>
>
>                ^^^^^^^^^^^^^^^
> Are you trying to impersonate me?
>
> Can you reply again with the proper Reviewed-by tag? ;)
>
>
> Yours sincerely,
> Vincent Mailhol

Reviewed-by: Pavel Pisa <pisa@fel.cvut.cz>

Excuse, I have been in too much hurry.

Best wishes,

                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 v3] docs: Fix kernel-doc error in CAN driver

[Vincent Mailhol]

On 22/07/2025 at 16:57, Pavel Pisa wrote:
> On Tuesday 22 of July 2025 09:27:39 Vincent Mailhol wrote:
>> On 22/07/2025 at 15:37, Pavel Pisa wrote:
>>> On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
>>>> On 22/07/2025 at 12:53, Luis Felipe Hernandez wrote:
>>>>> Fix kernel-doc formatting issue causing unexpected indentation error
>>>>> in ctucanfd driver documentation build. Convert main return values
>>>>> to bullet list format while preserving numbered sub-list in order to
>>>>> correct indentation error and visual structure in rendered html.
>>>>>
>>>>> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
>>>>
>>>> Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>
>>>
>>> Reviewed-by: Vincent Mailhol <pisa@fel.cvut.cz>
>>
>>                ^^^^^^^^^^^^^^^
>> Are you trying to impersonate me?
>>
>> Can you reply again with the proper Reviewed-by tag? ;)
>>
>>
>> Yours sincerely,
>> Vincent Mailhol
> 
> Reviewed-by: Pavel Pisa <pisa@fel.cvut.cz>
> 
> Excuse, I have been in too much hurry.

No problem :)

Marc, b4 will not be able to manage the review tags correctly. Can you please
fix it manually when picking up the patch?


Yours sincerely,
Vincent Mailhol

Re: [PATCH v3] docs: Fix kernel-doc error in CAN driver

[Marc Kleine-Budde]

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

On 22.07.2025 17:50:56, Vincent Mailhol wrote:
> On 22/07/2025 at 16:57, Pavel Pisa wrote:
> > On Tuesday 22 of July 2025 09:27:39 Vincent Mailhol wrote:
> >> On 22/07/2025 at 15:37, Pavel Pisa wrote:
> >>> On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
> >>>> On 22/07/2025 at 12:53, Luis Felipe Hernandez wrote:
> >>>>> Fix kernel-doc formatting issue causing unexpected indentation error
> >>>>> in ctucanfd driver documentation build. Convert main return values
> >>>>> to bullet list format while preserving numbered sub-list in order to
> >>>>> correct indentation error and visual structure in rendered html.
> >>>>>
> >>>>> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> >>>>
> >>>> Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>
> >>>
> >>> Reviewed-by: Vincent Mailhol <pisa@fel.cvut.cz>
> >>
> >>                ^^^^^^^^^^^^^^^
> >> Are you trying to impersonate me?
> >>
> >> Can you reply again with the proper Reviewed-by tag? ;)
> >>
> >>
> >> Yours sincerely,
> >> Vincent Mailhol
> > 
> > Reviewed-by: Pavel Pisa <pisa@fel.cvut.cz>
> > 
> > Excuse, I have been in too much hurry.
> 
> No problem :)
> 
> Marc, b4 will not be able to manage the review tags correctly. Can you please
> fix it manually when picking up the patch?

Thanks, for the heads up.

I wrote to the tools mailing list and described the problem, maybe
someone comes up with a fix.

Applied to linux-can-next.

Grüße,
Marc

-- 
Pengutronix e.K.                 | Marc Kleine-Budde          |
Embedded Linux                   | https://www.pengutronix.de |
Vertretung Nürnberg              | Phone: +49-5121-206917-129 |
Amtsgericht Hildesheim, HRA 2686 | Fax:   +49-5121-206917-9   |

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

Re: [PATCH v3] docs: Fix kernel-doc error in CAN driver

[Randy Dunlap]

On 7/21/25 8:53 PM, Luis Felipe Hernandez wrote:
> Fix kernel-doc formatting issue causing unexpected indentation error
> in ctucanfd driver documentation build. Convert main return values
> to bullet list format while preserving numbered sub-list in order to
> correct indentation error and visual structure in rendered html.
> 
> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> 
> ---
> Changes since v2:
> - Focus only on CAN driver (GPU and I3C already fixed by Bagas Sanjaya)
> - Remove blank line that caused unwanted 'Description' output
> - Keep numbered sub-list format as suggested by Randy Dunlap
> - Move changelog after cutter as suggested by Vincent Mailhol
> 
> Link(v2): https://lore.kernel.org/all/20250720152401.70720-1-luis.hernandez093@gmail.com/
> Link(v1): https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/
> ---
>  drivers/net/can/ctucanfd/ctucanfd_base.c | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)
> 
> diff --git a/drivers/net/can/ctucanfd/ctucanfd_base.c b/drivers/net/can/ctucanfd/ctucanfd_base.c
> index bf6398772960..8bd3f0fc385c 100644
> --- a/drivers/net/can/ctucanfd/ctucanfd_base.c
> +++ b/drivers/net/can/ctucanfd/ctucanfd_base.c
> @@ -506,11 +506,12 @@ static bool ctucan_is_txt_buf_writable(struct ctucan_priv *priv, u8 buf)
>   * @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)

Looks good. Thanks for doing this.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy