Skip to contentSkip to conversation

docs: Fix kernel-doc error in CAN driver

PATCH Applied Luis Felipe Hernandez 5 participants 8 messages Jul 22, 2025

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 docs: Fix kernel-doc error in CAN driver

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.

---
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/[email protected]/
Link(v1): https://lore.kernel.org/all/[email protected]/

---
 drivers/net/can/ctucanfd/ctucanfd_base.c | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
drivers/net/can/ctucanfd/ctucanfd_base.c +6 -5
index bf6398772960..8bd3f0fc385c 100644
@@ -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)
Signature · 1 line
2.43.0
Reviewed-by on v3 1/1
#1 lore raw
Quoted 6 lines · 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.

Yours sincerely,
Vincent Mailhol

Reviewed-by
#2 lore raw
Quoted 9 lines · On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
Quoted 6 lines · 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.

This version keeps readability in the plain source.

Best wishes,

Pavel

Pavel Pisa
phone: +420 603531357
e-mail: [email protected]
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

#3 lore raw
Quoted 7 lines · Pavel Pisa
Quoted 6 lines · On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
Quoted 5 lines · 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.

Quoted 5 lines
Quoted 3 lines
Quoted 1 line
               ^^^^^^^^^^^^^^^

Are you trying to impersonate me?

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

Yours sincerely,
Vincent Mailhol

Reviewed-by
#4 lore raw
Quoted 14 lines · On Tuesday 22 of July 2025 09:27:39 Vincent Mailhol wrote:
Quoted 7 lines · Pavel Pisa
Quoted 6 lines · On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
Quoted 5 lines · 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.

Quoted 5 lines
Quoted 3 lines
Quoted 1 line
Quoted 8 lines
               ^^^^^^^^^^^^^^^

Are you trying to impersonate me?

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

Yours sincerely,
Vincent Mailhol

Excuse, I have been in too much hurry.

Best wishes,

Pavel Pisa
phone: +420 603531357
e-mail: [email protected]
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

#5 lore raw
Quoted 21 lines · Pavel Pisa
Quoted 20 lines · On Tuesday 22 of July 2025 09:27:39 Vincent Mailhol wrote:
Quoted 7 lines · Pavel Pisa
Quoted 6 lines · On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
Quoted 5 lines · 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.

Quoted 5 lines
Quoted 3 lines
Quoted 1 line
               ^^^^^^^^^^^^^^^

Are you trying to impersonate me?

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

Quoted 6 lines
Quoted 2 lines

Yours sincerely,
Vincent Mailhol

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

maintainer Applied
#6 lore raw
Quoted 25 lines · Vincent Mailhol
Quoted 24 lines · Pavel Pisa
Quoted 22 lines · On Tuesday 22 of July 2025 09:27:39 Vincent Mailhol wrote:
Quoted 7 lines · Pavel Pisa
Quoted 6 lines · On Tuesday 22 of July 2025 06:06:30 Vincent Mailhol wrote:
Quoted 5 lines · 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.

Quoted 5 lines
Quoted 3 lines
Quoted 1 line
               ^^^^^^^^^^^^^^^

Are you trying to impersonate me?

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

Yours sincerely,
Vincent Mailhol

Quoted 8 lines
Quoted 3 lines

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

Signature · 4 lines
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   |
Reviewed-by Tested-by on v3 1/1
#7 lore raw
In reply to Luis Felipe Hernandez
Quoted 32 lines · 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.

---
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/[email protected]/
Link(v1): https://lore.kernel.org/all/[email protected]/

---
 drivers/net/can/ctucanfd/ctucanfd_base.c | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
drivers/net/can/ctucanfd/ctucanfd_base.c +0 -4
index bf6398772960..8bd3f0fc385c 100644
@@ -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

drivers/net/can/ctucanfd/ctucanfd_base.c static bool ctucan_is_txt_buf_writable(struct ctucan_priv *priv, u8 buf) · line 517

Quoted 10 lines
drivers/net/can/ctucanfd/ctucanfd_base.c +6 -1
- *			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.

Signature · 1 line
~Randy