[PATCH v2] docs: Fix kernel-doc indentation errors

[PATCH v2] docs: Fix kernel-doc indentation errors

[Luis Felipe Hernandez]

This is v2 of the patch to fix kernel-doc formatting issues.

Changes since v1:
- Convert problematic sections to proper ReST list format instead of 
  just fixing indentation (feedback from Randy Dunlap)
- Add GPU driver fixes (additional files with same issue found on latest
  build in linux-next)
- Remove SCSI driver (already fixed in current tree)

---
v1: https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/

Luis Felipe Hernandez (1):
  docs: Fix kernel-doc indentation errors

 drivers/gpu/drm/drm_gpuvm.c              | 16 ++++++++--------
 drivers/i3c/device.c                     | 13 ++++++++-----
 drivers/net/can/ctucanfd/ctucanfd_base.c | 12 +++++++-----
 3 files changed, 23 insertions(+), 18 deletions(-)

-- 
2.43.0

[PATCH v2 1/1] docs: Fix kernel-doc indentation errors

[Luis Felipe Hernandez]

Fix kernel-doc issues that reported Unexpected indentation errors
durring documentation build (make htmldocs) in CAN, I3C and GPU drivers.

Convert formatting to proper ReST list syntax to resolve warning.

Changes since v1:
- Convert return value descriptions to proper ReST format
- Fix code block introduction with :: syntax  
- Add GPU driver fixes
- Remove SCSI driver (already fixed)

Link: https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/

Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
---
 drivers/gpu/drm/drm_gpuvm.c              | 16 ++++++++--------
 drivers/i3c/device.c                     | 13 ++++++++-----
 drivers/net/can/ctucanfd/ctucanfd_base.c | 12 +++++++-----
 3 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/drivers/gpu/drm/drm_gpuvm.c b/drivers/gpu/drm/drm_gpuvm.c
index bbc7fecb6f4a..982a3476a988 100644
--- a/drivers/gpu/drm/drm_gpuvm.c
+++ b/drivers/gpu/drm/drm_gpuvm.c
@@ -2430,7 +2430,7 @@ static const struct drm_gpuvm_ops lock_ops = {
  * remapped, and locks+prepares (drm_exec_prepare_object()) objects that
  * will be newly mapped.
  *
- * The expected usage is:
+ * The expected usage is::
  *
  *    vm_bind {
  *        struct drm_exec exec;
@@ -2464,14 +2464,14 @@ static const struct drm_gpuvm_ops lock_ops = {
  * op, because the later altered step will involve the same GEM object(s)
  * already seen in the earlier locking step.  For example:
  *
- * 1) An earlier driver DRIVER_OP_UNMAP op removes the need for a
- *    DRM_GPUVA_OP_REMAP/UNMAP step.  This is safe because we've already
- *    locked the GEM object in the earlier DRIVER_OP_UNMAP op.
+ * * An earlier driver DRIVER_OP_UNMAP op removes the need for a
+ *   DRM_GPUVA_OP_REMAP/UNMAP step.  This is safe because we've already
+ *   locked the GEM object in the earlier DRIVER_OP_UNMAP op.
  *
- * 2) An earlier DRIVER_OP_MAP op overlaps with a later DRIVER_OP_MAP/UNMAP
- *    op, introducing a DRM_GPUVA_OP_REMAP/UNMAP that wouldn't have been
- *    required without the earlier DRIVER_OP_MAP.  This is safe because we've
- *    already locked the GEM object in the earlier DRIVER_OP_MAP step.
+ * * An earlier DRIVER_OP_MAP op overlaps with a later DRIVER_OP_MAP/UNMAP
+ *   op, introducing a DRM_GPUVA_OP_REMAP/UNMAP that wouldn't have been
+ *   required without the earlier DRIVER_OP_MAP.  This is safe because we've
+ *   already locked the GEM object in the earlier DRIVER_OP_MAP step.
  *
  * Returns: 0 on success or a negative error codec
  */
diff --git a/drivers/i3c/device.c b/drivers/i3c/device.c
index e80e48756914..48b49757a90b 100644
--- a/drivers/i3c/device.c
+++ b/drivers/i3c/device.c
@@ -26,11 +26,14 @@
  *
  * This function can sleep and thus cannot be called in atomic context.
  *
- * 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.
+ * 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.
+ *
  */
 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..f910422188c3 100644
--- a/drivers/net/can/ctucanfd/ctucanfd_base.c
+++ b/drivers/net/can/ctucanfd/ctucanfd_base.c
@@ -506,11 +506,13 @@ 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:
+ *
+ *   * TXT Buffer is not writable (it is in wrong state)
+ *   * Invalid TXT buffer index
+ *   * 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 v2 1/1] docs: Fix kernel-doc indentation errors

[Randy Dunlap]

+ Bagas

On 7/20/25 8:24 AM, Luis Felipe Hernandez wrote:
> Fix kernel-doc issues that reported Unexpected indentation errors
> durring documentation build (make htmldocs) in CAN, I3C and GPU drivers.
> 
> Convert formatting to proper ReST list syntax to resolve warning.
> 
> Changes since v1:
> - Convert return value descriptions to proper ReST format
> - Fix code block introduction with :: syntax  
> - Add GPU driver fixes
> - Remove SCSI driver (already fixed)
> 
> Link: https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/
> 
> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> ---
>  drivers/gpu/drm/drm_gpuvm.c              | 16 ++++++++--------

drm_gpuvm.c fixed by Bagas:

  https://lore.kernel.org/linux-doc/20250709024501.9105-1-bagasdotme@gmail.com/

Otherwise LGTM.

>  drivers/i3c/device.c                     | 13 ++++++++-----

i3c is also fixed by Bagas:
  https://lore.kernel.org/linux-i3c/20250702040424.18577-1-bagasdotme@gmail.com/

Otherwise LGTM.

>  drivers/net/can/ctucanfd/ctucanfd_base.c | 12 +++++++-----
>  3 files changed, 23 insertions(+), 18 deletions(-)
> 

> diff --git a/drivers/net/can/ctucanfd/ctucanfd_base.c b/drivers/net/can/ctucanfd/ctucanfd_base.c
> index bf6398772960..f910422188c3 100644
> --- a/drivers/net/can/ctucanfd/ctucanfd_base.c
> +++ b/drivers/net/can/ctucanfd/ctucanfd_base.c
> @@ -506,11 +506,13 @@ 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:
> + *
> + *   * TXT Buffer is not writable (it is in wrong state)
> + *   * Invalid TXT buffer index
> + *   * Invalid frame length
>   */
>  static bool ctucan_insert_frame(struct ctucan_priv *priv, const struct canfd_frame *cf, u8 buf,
>  				bool isfdf)

The numbered list is not a problem AFAIK. Did you see an issue with it?
And having the blank line just before the "False" list causing undesirable
html output:

Return

 * True - Frame inserted successfully

 * False - Frame was not inserted due to one of:

Description

 * TXT Buffer is not writable (it is in wrong state)

 * Invalid TXT buffer index

 * Invalid frame length

The "Description" line should not be there.

IMO all we want to do is convert the True and False lines into
a bulleted list and then the html output will look 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


-- 
~Randy

Re: [PATCH v2 1/1] docs: Fix kernel-doc indentation errors

[Felipe Hernandez]

On Sun, Jul 20, 2025 at 3:03 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
> + Bagas
>
> On 7/20/25 8:24 AM, Luis Felipe Hernandez wrote:
> > Fix kernel-doc issues that reported Unexpected indentation errors
> > durring documentation build (make htmldocs) in CAN, I3C and GPU drivers.
> >
> > Convert formatting to proper ReST list syntax to resolve warning.
> >
> > Changes since v1:
> > - Convert return value descriptions to proper ReST format
> > - Fix code block introduction with :: syntax
> > - Add GPU driver fixes
> > - Remove SCSI driver (already fixed)
> >
> > Link: https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/
> >
> > Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> > ---
> >  drivers/gpu/drm/drm_gpuvm.c              | 16 ++++++++--------
>
> drm_gpuvm.c fixed by Bagas:
>
>   https://lore.kernel.org/linux-doc/20250709024501.9105-1-bagasdotme@gmail.com/
>
> Otherwise LGTM.
>
> >  drivers/i3c/device.c                     | 13 ++++++++-----
>
> i3c is also fixed by Bagas:
>   https://lore.kernel.org/linux-i3c/20250702040424.18577-1-bagasdotme@gmail.com/
>
> Otherwise LGTM.
>
> >  drivers/net/can/ctucanfd/ctucanfd_base.c | 12 +++++++-----
> >  3 files changed, 23 insertions(+), 18 deletions(-)
> >
>
> > diff --git a/drivers/net/can/ctucanfd/ctucanfd_base.c b/drivers/net/can/ctucanfd/ctucanfd_base.c
> > index bf6398772960..f910422188c3 100644
> > --- a/drivers/net/can/ctucanfd/ctucanfd_base.c
> > +++ b/drivers/net/can/ctucanfd/ctucanfd_base.c
> > @@ -506,11 +506,13 @@ 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:
> > + *
> > + *   * TXT Buffer is not writable (it is in wrong state)
> > + *   * Invalid TXT buffer index
> > + *   * Invalid frame length
> >   */
> >  static bool ctucan_insert_frame(struct ctucan_priv *priv, const struct canfd_frame *cf, u8 buf,
> >                               bool isfdf)
>
> The numbered list is not a problem AFAIK. Did you see an issue with it?
> And having the blank line just before the "False" list causing undesirable
> html output:
>
> Return
>
>  * True - Frame inserted successfully
>
>  * False - Frame was not inserted due to one of:
>
> Description
>
>  * TXT Buffer is not writable (it is in wrong state)
>
>  * Invalid TXT buffer index
>
>  * Invalid frame length
>
> The "Description" line should not be there.
>
> IMO all we want to do is convert the True and False lines into
> a bulleted list and then the html output will look 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
>
>
> --
> ~Randy

Hi Randy,

Thank you for the feedback, I apologize about the issues with this
latest patch version:

1. I now see that Bagas has already fixed the GPU and I3C drivers... I
apologize for the duplicate effort.

2. For the CAN driver, I understand your point about the blank line
causing unwanted issues with the HTML. I'll correct this.

3. Re the numbered list> I was being overly broad in my conversion to
bullet format. I will back this out.

I'll send a v3 that focuses only on the CAN driver fix with the
correct formatting you described (convert True/False to bullets while
keeping the numbered sub list intact).

Thank you for the guidance

Best,

Felipe

Re: [PATCH v2 1/1] docs: Fix kernel-doc indentation errors

[Vincent Mailhol]

On 21/07/2025 at 00:24, Luis Felipe Hernandez wrote:
> Fix kernel-doc issues that reported Unexpected indentation errors
> durring documentation build (make htmldocs) in CAN, I3C and GPU drivers.
  ^^^^^^^
during

> Convert formatting to proper ReST list syntax to resolve warning.
> 
> Changes since v1:
> - Convert return value descriptions to proper ReST format
> - Fix code block introduction with :: syntax  
> - Add GPU driver fixes
> - Remove SCSI driver (already fixed)At

The change log does not need to appear in the patch main body.

Add a --- cutter after your signature and put the change log after that cutter.
This way, the change log will automatically be discarded when the patch is picked.

> Link: https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/
> 
> Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> ---
>  drivers/gpu/drm/drm_gpuvm.c              | 16 ++++++++--------
>  drivers/i3c/device.c                     | 13 ++++++++-----
>  drivers/net/can/ctucanfd/ctucanfd_base.c | 12 +++++++-----

Can you do one patch per sub-domains and send them separately? The maintainers
of drivers/i3c/ are not the same as the maintainers of drivers/net/can/. And
there is no dependencies preventing you to split.


Yours sincerely,
Vincent Mailhol

Re: [PATCH v2 1/1] docs: Fix kernel-doc indentation errors

[Felipe Hernandez]

On Mon, Jul 21, 2025 at 3:48 AM Vincent Mailhol
<mailhol.vincent@wanadoo.fr> wrote:
>
> On 21/07/2025 at 00:24, Luis Felipe Hernandez wrote:
> > Fix kernel-doc issues that reported Unexpected indentation errors
> > durring documentation build (make htmldocs) in CAN, I3C and GPU drivers.
>   ^^^^^^^
> during
>
> > Convert formatting to proper ReST list syntax to resolve warning.
> >
> > Changes since v1:
> > - Convert return value descriptions to proper ReST format
> > - Fix code block introduction with :: syntax
> > - Add GPU driver fixes
> > - Remove SCSI driver (already fixed)At
>
> The change log does not need to appear in the patch main body.
>
> Add a --- cutter after your signature and put the change log after that cutter.
> This way, the change log will automatically be discarded when the patch is picked.
>
> > Link: https://lore.kernel.org/all/20250703023511.82768-1-luis.hernandez093@gmail.com/
> >
> > Signed-off-by: Luis Felipe Hernandez <luis.hernandez093@gmail.com>
> > ---
> >  drivers/gpu/drm/drm_gpuvm.c              | 16 ++++++++--------
> >  drivers/i3c/device.c                     | 13 ++++++++-----
> >  drivers/net/can/ctucanfd/ctucanfd_base.c | 12 +++++++-----
>
> Can you do one patch per sub-domains and send them separately? The maintainers
> of drivers/i3c/ are not the same as the maintainers of drivers/net/can/. And
> there is no dependencies preventing you to split.
>
>
> Yours sincerely,
> Vincent Mailhol
>

Hi Vincent,

Thank you for taking time to review my v2 patch and for the feedback.
I have since applied the changes you suggested. I apologize about
mixing the sub-domains, at first I thought they would all be related
as being part of the documentation subsystem since they were reporting
a similar error but I now understand these weren't documentation
related per-se and should've gone to each of the sub-domains
separately as the changes were made in the sources.

Again, I appreciate the guidance!

Best,

Felipe