[RFC PATCH 0/2] kernel-doc: Do not pre-process comments

[RFC PATCH 0/2] kernel-doc: Do not pre-process comments

[Anna-Maria Behnsen]

Hi,

this is a RFC as I'm not quite sure if this change has some subtle side
effect.

Commit 654784284430 ("kernel-doc: bugfix - multi-line macros") introduces
pre-processing of backslashes at the end of a line to not break multi-line
macros. This pre-processing is done independently if it is inside code or
inside a comment.

This illustation of a hierarchy as a code block inside a kernel-doc comment
has a backslash at the end of the line:

---8<---
/**
 * DOC: hierarchy
 *
 *                    Top Level
 *                /               \
 *         Child A                 Child B
 */
---8<---

It will be displayed as:

---8<---
	     Top Level
	 /                *        Child A                 Child B
---8<---


As I asked for a solution on the linux-doc mailing list, I got some
suggestions with workarounds and also got the suggestion by Matthew Wilcox
to adapt the backslash preprocessing in kernel-doc script. I tested it and
fixed then the newly produced warnings which are covered in the first
patch. The processing of the documentation seems to work - but please don't
rely only on my tests as I'm not a perl neither a kernel-doc expert.

Thanks,

	Anna-Maria



Anna-Maria Behnsen (2):
  drm/vram-helper: Fix 'multi-line' kernel-doc comments
  scripts/kernel-doc: Do not process backslash lines in comments

 drivers/gpu/drm/drm_gem_vram_helper.c | 44 ++++++++++++---------------
 include/drm/drm_gem_vram_helper.h     | 16 +++++-----
 scripts/kernel-doc                    |  2 +-
 3 files changed, 29 insertions(+), 33 deletions(-)

-- 
2.39.2

[RFC PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments

[Anna-Maria Behnsen]

Reformat lines in kernel-doc comments, which make use of the backslash at
the end to suggest it is a multi-line comment. kernel-doc is able to
process e.g. the short description of a function properly, even if it is
across two lines.

No functional change.

Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
---
 drivers/gpu/drm/drm_gem_vram_helper.c | 44 ++++++++++++---------------
 include/drm/drm_gem_vram_helper.h     | 16 +++++-----
 2 files changed, 28 insertions(+), 32 deletions(-)

diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
index b67eafa55715..b7d42210fccc 100644
--- a/drivers/gpu/drm/drm_gem_vram_helper.c
+++ b/drivers/gpu/drm/drm_gem_vram_helper.c
@@ -260,8 +260,7 @@ static u64 drm_gem_vram_pg_offset(struct drm_gem_vram_object *gbo)
 }
 
 /**
- * drm_gem_vram_offset() - \
-	Returns a GEM VRAM object's offset in video memory
+ * drm_gem_vram_offset() - Returns a GEM VRAM object's offset in video memory
  * @gbo:	the GEM VRAM object
  *
  * This function returns the buffer object's offset in the device's video
@@ -470,14 +469,15 @@ void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo,
 EXPORT_SYMBOL(drm_gem_vram_vunmap);
 
 /**
- * drm_gem_vram_fill_create_dumb() - \
-	Helper for implementing &struct drm_driver.dumb_create
+ * drm_gem_vram_fill_create_dumb() - Helper for implementing
+ *				     &struct drm_driver.dumb_create
+ *
  * @file:		the DRM file
  * @dev:		the DRM device
  * @pg_align:		the buffer's alignment in multiples of the page size
  * @pitch_align:	the scanline's alignment in powers of 2
- * @args:		the arguments as provided to \
-				&struct drm_driver.dumb_create
+ * @args:		the arguments as provided to
+ *			&struct drm_driver.dumb_create
  *
  * This helper function fills &struct drm_mode_create_dumb, which is used
  * by &struct drm_driver.dumb_create. Implementations of this interface
@@ -575,8 +575,7 @@ static int drm_gem_vram_bo_driver_move(struct drm_gem_vram_object *gbo,
  */
 
 /**
- * drm_gem_vram_object_free() - \
-	Implements &struct drm_gem_object_funcs.free
+ * drm_gem_vram_object_free() - Implements &struct drm_gem_object_funcs.free
  * @gem:       GEM object. Refers to &struct drm_gem_vram_object.gem
  */
 static void drm_gem_vram_object_free(struct drm_gem_object *gem)
@@ -591,12 +590,11 @@ static void drm_gem_vram_object_free(struct drm_gem_object *gem)
  */
 
 /**
- * drm_gem_vram_driver_dumb_create() - \
-	Implements &struct drm_driver.dumb_create
+ * drm_gem_vram_driver_dumb_create() - Implements &struct drm_driver.dumb_create
  * @file:		the DRM file
  * @dev:		the DRM device
- * @args:		the arguments as provided to \
-				&struct drm_driver.dumb_create
+ * @args:		the arguments as provided to
+ *			&struct drm_driver.dumb_create
  *
  * This function requires the driver to use @drm_device.vram_mm for its
  * instance of VRAM MM.
@@ -639,8 +637,8 @@ static void __drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
 }
 
 /**
- * drm_gem_vram_plane_helper_prepare_fb() - \
- *	Implements &struct drm_plane_helper_funcs.prepare_fb
+ * drm_gem_vram_plane_helper_prepare_fb() - Implements &struct
+ *					    drm_plane_helper_funcs.prepare_fb
  * @plane:	a DRM plane
  * @new_state:	the plane's new state
  *
@@ -690,8 +688,8 @@ drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
 EXPORT_SYMBOL(drm_gem_vram_plane_helper_prepare_fb);
 
 /**
- * drm_gem_vram_plane_helper_cleanup_fb() - \
- *	Implements &struct drm_plane_helper_funcs.cleanup_fb
+ * drm_gem_vram_plane_helper_cleanup_fb() - Implements &struct
+ *					    drm_plane_helper_funcs.cleanup_fb
  * @plane:	a DRM plane
  * @old_state:	the plane's old state
  *
@@ -717,8 +715,8 @@ EXPORT_SYMBOL(drm_gem_vram_plane_helper_cleanup_fb);
  */
 
 /**
- * drm_gem_vram_simple_display_pipe_prepare_fb() - \
- *	Implements &struct drm_simple_display_pipe_funcs.prepare_fb
+ * drm_gem_vram_simple_display_pipe_prepare_fb() - Implements &struct
+ *				   drm_simple_display_pipe_funcs.prepare_fb
  * @pipe:	a simple display pipe
  * @new_state:	the plane's new state
  *
@@ -739,8 +737,8 @@ int drm_gem_vram_simple_display_pipe_prepare_fb(
 EXPORT_SYMBOL(drm_gem_vram_simple_display_pipe_prepare_fb);
 
 /**
- * drm_gem_vram_simple_display_pipe_cleanup_fb() - \
- *	Implements &struct drm_simple_display_pipe_funcs.cleanup_fb
+ * drm_gem_vram_simple_display_pipe_cleanup_fb() - Implements &struct
+ *						   drm_simple_display_pipe_funcs.cleanup_fb
  * @pipe:	a simple display pipe
  * @old_state:	the plane's old state
  *
@@ -761,8 +759,7 @@ EXPORT_SYMBOL(drm_gem_vram_simple_display_pipe_cleanup_fb);
  */
 
 /**
- * drm_gem_vram_object_pin() - \
-	Implements &struct drm_gem_object_funcs.pin
+ * drm_gem_vram_object_pin() - Implements &struct drm_gem_object_funcs.pin
  * @gem:	The GEM object to pin
  *
  * Returns:
@@ -785,8 +782,7 @@ static int drm_gem_vram_object_pin(struct drm_gem_object *gem)
 }
 
 /**
- * drm_gem_vram_object_unpin() - \
-	Implements &struct drm_gem_object_funcs.unpin
+ * drm_gem_vram_object_unpin() - Implements &struct drm_gem_object_funcs.unpin
  * @gem:	The GEM object to unpin
  */
 static void drm_gem_vram_object_unpin(struct drm_gem_object *gem)
diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
index e18429f09e53..2938ba80750d 100644
--- a/include/drm/drm_gem_vram_helper.h
+++ b/include/drm/drm_gem_vram_helper.h
@@ -33,8 +33,8 @@ struct vm_area_struct;
  * struct drm_gem_vram_object - GEM object backed by VRAM
  * @bo:		TTM buffer object
  * @map:	Mapping information for @bo
- * @placement:	TTM placement information. Supported placements are \
-	%TTM_PL_VRAM and %TTM_PL_SYSTEM
+ * @placement:	TTM placement information. Supported placements are %TTM_PL_VRAM
+ *		and %TTM_PL_SYSTEM
  * @placements:	TTM placement information.
  *
  * The type struct drm_gem_vram_object represents a GEM object that is
@@ -126,8 +126,8 @@ drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
 				     struct drm_plane_state *old_state);
 
 /**
- * DRM_GEM_VRAM_PLANE_HELPER_FUNCS -
- *	Initializes struct drm_plane_helper_funcs for VRAM handling
+ * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - Initializes struct drm_plane_helper_funcs
+ *				     for VRAM handling
  *
  * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This
  * macro initializes struct drm_plane_helper_funcs to use the respective helper
@@ -150,8 +150,8 @@ void drm_gem_vram_simple_display_pipe_cleanup_fb(
 	struct drm_plane_state *old_state);
 
 /**
- * define DRM_GEM_VRAM_DRIVER - default callback functions for \
-	&struct drm_driver
+ * define DRM_GEM_VRAM_DRIVER - default callback functions for
+ *				&struct drm_driver
  *
  * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
  * &struct drm_driver with default functions.
@@ -185,8 +185,8 @@ struct drm_vram_mm {
 };
 
 /**
- * drm_vram_mm_of_bdev() - \
-	Returns the container of type &struct ttm_device for field bdev.
+ * drm_vram_mm_of_bdev() - Returns the container of type &struct ttm_device for
+ *			   field bdev.
  * @bdev:	the TTM BO device
  *
  * Returns:
-- 
2.39.2

Re: [RFC PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments

[Jani Nikula]

On Tue, 16 Jan 2024, Anna-Maria Behnsen <anna-maria@linutronix.de> wrote:
> Reformat lines in kernel-doc comments, which make use of the backslash at
> the end to suggest it is a multi-line comment. kernel-doc is able to
> process e.g. the short description of a function properly, even if it is
> across two lines.
>
> No functional change.
>
> Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>

Should be sent to dri-devel.

Reviewed-by: Jani Nikula <jani.nikula@intel.com>

> ---
>  drivers/gpu/drm/drm_gem_vram_helper.c | 44 ++++++++++++---------------
>  include/drm/drm_gem_vram_helper.h     | 16 +++++-----
>  2 files changed, 28 insertions(+), 32 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_gem_vram_helper.c b/drivers/gpu/drm/drm_gem_vram_helper.c
> index b67eafa55715..b7d42210fccc 100644
> --- a/drivers/gpu/drm/drm_gem_vram_helper.c
> +++ b/drivers/gpu/drm/drm_gem_vram_helper.c
> @@ -260,8 +260,7 @@ static u64 drm_gem_vram_pg_offset(struct drm_gem_vram_object *gbo)
>  }
>  
>  /**
> - * drm_gem_vram_offset() - \
> -	Returns a GEM VRAM object's offset in video memory
> + * drm_gem_vram_offset() - Returns a GEM VRAM object's offset in video memory
>   * @gbo:	the GEM VRAM object
>   *
>   * This function returns the buffer object's offset in the device's video
> @@ -470,14 +469,15 @@ void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo,
>  EXPORT_SYMBOL(drm_gem_vram_vunmap);
>  
>  /**
> - * drm_gem_vram_fill_create_dumb() - \
> -	Helper for implementing &struct drm_driver.dumb_create
> + * drm_gem_vram_fill_create_dumb() - Helper for implementing
> + *				     &struct drm_driver.dumb_create
> + *
>   * @file:		the DRM file
>   * @dev:		the DRM device
>   * @pg_align:		the buffer's alignment in multiples of the page size
>   * @pitch_align:	the scanline's alignment in powers of 2
> - * @args:		the arguments as provided to \
> -				&struct drm_driver.dumb_create
> + * @args:		the arguments as provided to
> + *			&struct drm_driver.dumb_create
>   *
>   * This helper function fills &struct drm_mode_create_dumb, which is used
>   * by &struct drm_driver.dumb_create. Implementations of this interface
> @@ -575,8 +575,7 @@ static int drm_gem_vram_bo_driver_move(struct drm_gem_vram_object *gbo,
>   */
>  
>  /**
> - * drm_gem_vram_object_free() - \
> -	Implements &struct drm_gem_object_funcs.free
> + * drm_gem_vram_object_free() - Implements &struct drm_gem_object_funcs.free
>   * @gem:       GEM object. Refers to &struct drm_gem_vram_object.gem
>   */
>  static void drm_gem_vram_object_free(struct drm_gem_object *gem)
> @@ -591,12 +590,11 @@ static void drm_gem_vram_object_free(struct drm_gem_object *gem)
>   */
>  
>  /**
> - * drm_gem_vram_driver_dumb_create() - \
> -	Implements &struct drm_driver.dumb_create
> + * drm_gem_vram_driver_dumb_create() - Implements &struct drm_driver.dumb_create
>   * @file:		the DRM file
>   * @dev:		the DRM device
> - * @args:		the arguments as provided to \
> -				&struct drm_driver.dumb_create
> + * @args:		the arguments as provided to
> + *			&struct drm_driver.dumb_create
>   *
>   * This function requires the driver to use @drm_device.vram_mm for its
>   * instance of VRAM MM.
> @@ -639,8 +637,8 @@ static void __drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
>  }
>  
>  /**
> - * drm_gem_vram_plane_helper_prepare_fb() - \
> - *	Implements &struct drm_plane_helper_funcs.prepare_fb
> + * drm_gem_vram_plane_helper_prepare_fb() - Implements &struct
> + *					    drm_plane_helper_funcs.prepare_fb
>   * @plane:	a DRM plane
>   * @new_state:	the plane's new state
>   *
> @@ -690,8 +688,8 @@ drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
>  EXPORT_SYMBOL(drm_gem_vram_plane_helper_prepare_fb);
>  
>  /**
> - * drm_gem_vram_plane_helper_cleanup_fb() - \
> - *	Implements &struct drm_plane_helper_funcs.cleanup_fb
> + * drm_gem_vram_plane_helper_cleanup_fb() - Implements &struct
> + *					    drm_plane_helper_funcs.cleanup_fb
>   * @plane:	a DRM plane
>   * @old_state:	the plane's old state
>   *
> @@ -717,8 +715,8 @@ EXPORT_SYMBOL(drm_gem_vram_plane_helper_cleanup_fb);
>   */
>  
>  /**
> - * drm_gem_vram_simple_display_pipe_prepare_fb() - \
> - *	Implements &struct drm_simple_display_pipe_funcs.prepare_fb
> + * drm_gem_vram_simple_display_pipe_prepare_fb() - Implements &struct
> + *				   drm_simple_display_pipe_funcs.prepare_fb
>   * @pipe:	a simple display pipe
>   * @new_state:	the plane's new state
>   *
> @@ -739,8 +737,8 @@ int drm_gem_vram_simple_display_pipe_prepare_fb(
>  EXPORT_SYMBOL(drm_gem_vram_simple_display_pipe_prepare_fb);
>  
>  /**
> - * drm_gem_vram_simple_display_pipe_cleanup_fb() - \
> - *	Implements &struct drm_simple_display_pipe_funcs.cleanup_fb
> + * drm_gem_vram_simple_display_pipe_cleanup_fb() - Implements &struct
> + *						   drm_simple_display_pipe_funcs.cleanup_fb
>   * @pipe:	a simple display pipe
>   * @old_state:	the plane's old state
>   *
> @@ -761,8 +759,7 @@ EXPORT_SYMBOL(drm_gem_vram_simple_display_pipe_cleanup_fb);
>   */
>  
>  /**
> - * drm_gem_vram_object_pin() - \
> -	Implements &struct drm_gem_object_funcs.pin
> + * drm_gem_vram_object_pin() - Implements &struct drm_gem_object_funcs.pin
>   * @gem:	The GEM object to pin
>   *
>   * Returns:
> @@ -785,8 +782,7 @@ static int drm_gem_vram_object_pin(struct drm_gem_object *gem)
>  }
>  
>  /**
> - * drm_gem_vram_object_unpin() - \
> -	Implements &struct drm_gem_object_funcs.unpin
> + * drm_gem_vram_object_unpin() - Implements &struct drm_gem_object_funcs.unpin
>   * @gem:	The GEM object to unpin
>   */
>  static void drm_gem_vram_object_unpin(struct drm_gem_object *gem)
> diff --git a/include/drm/drm_gem_vram_helper.h b/include/drm/drm_gem_vram_helper.h
> index e18429f09e53..2938ba80750d 100644
> --- a/include/drm/drm_gem_vram_helper.h
> +++ b/include/drm/drm_gem_vram_helper.h
> @@ -33,8 +33,8 @@ struct vm_area_struct;
>   * struct drm_gem_vram_object - GEM object backed by VRAM
>   * @bo:		TTM buffer object
>   * @map:	Mapping information for @bo
> - * @placement:	TTM placement information. Supported placements are \
> -	%TTM_PL_VRAM and %TTM_PL_SYSTEM
> + * @placement:	TTM placement information. Supported placements are %TTM_PL_VRAM
> + *		and %TTM_PL_SYSTEM
>   * @placements:	TTM placement information.
>   *
>   * The type struct drm_gem_vram_object represents a GEM object that is
> @@ -126,8 +126,8 @@ drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
>  				     struct drm_plane_state *old_state);
>  
>  /**
> - * DRM_GEM_VRAM_PLANE_HELPER_FUNCS -
> - *	Initializes struct drm_plane_helper_funcs for VRAM handling
> + * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - Initializes struct drm_plane_helper_funcs
> + *				     for VRAM handling
>   *
>   * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This
>   * macro initializes struct drm_plane_helper_funcs to use the respective helper
> @@ -150,8 +150,8 @@ void drm_gem_vram_simple_display_pipe_cleanup_fb(
>  	struct drm_plane_state *old_state);
>  
>  /**
> - * define DRM_GEM_VRAM_DRIVER - default callback functions for \
> -	&struct drm_driver
> + * define DRM_GEM_VRAM_DRIVER - default callback functions for
> + *				&struct drm_driver
>   *
>   * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
>   * &struct drm_driver with default functions.
> @@ -185,8 +185,8 @@ struct drm_vram_mm {
>  };
>  
>  /**
> - * drm_vram_mm_of_bdev() - \
> -	Returns the container of type &struct ttm_device for field bdev.
> + * drm_vram_mm_of_bdev() - Returns the container of type &struct ttm_device for
> + *			   field bdev.
>   * @bdev:	the TTM BO device
>   *
>   * Returns:

-- 
Jani Nikula, Intel

Re: [RFC PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments

[Anna-Maria Behnsen]

Jani Nikula <jani.nikula@linux.intel.com> writes:

> On Tue, 16 Jan 2024, Anna-Maria Behnsen <anna-maria@linutronix.de> wrote:
>> Reformat lines in kernel-doc comments, which make use of the backslash at
>> the end to suggest it is a multi-line comment. kernel-doc is able to
>> process e.g. the short description of a function properly, even if it is
>> across two lines.
>>
>> No functional change.
>>
>> Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
>
> Should be sent to dri-devel.
>
> Reviewed-by: Jani Nikula <jani.nikula@intel.com>

Thanks for the review. As it was a RFC and would only work if the doc
people are fine with the change, I decided not to bother all people in
advance. I'll resend it without RFC also to dri-devel.

Thanks,
        Anna-Maria

[RFC PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments

[Anna-Maria Behnsen]

Commit 654784284430 ("kernel-doc: bugfix - multi-line macros") introduces
pre-processing of backslashes at the end of a line to not break multi-line
macros. This pre-processing is done independently if it is inside code or
inside a comment.

This illustation of a hierarchy as a code block inside a kernel-doc comment
has a backslash at the end of the line:

---8<---
/**
 * DOC: hierarchy
 *
 *                    Top Level
 *                /               \
 *         Child A                 Child B
 */
---8<---

It will be displayed as:

---8<---
	     Top Level
	 /                *        Child A                 Child B
---8<---

To prevent this, do the pre-processing only for lines which are no
comments, e.g. do not start with ' *'.

Suggested-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e8aefd258a29..4277af79de86 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2331,7 +2331,7 @@ sub process_file($) {
 
     $section_counter = 0;
     while (<IN_FILE>) {
-	while (s/\\\s*$//) {
+	while (!/^ \*/ && s/\\\s*$//) {
 	    $_ .= <IN_FILE>;
 	}
 	# Replace tabs by spaces
-- 
2.39.2

Re: [RFC PATCH 0/2] kernel-doc: Do not pre-process comments

[Jonathan Corbet]

Anna-Maria Behnsen <anna-maria@linutronix.de> writes:

> this is a RFC as I'm not quite sure if this change has some subtle side
> effect.

Turns out it does, unfortunately.  Consider a hunk like this:

> /**
> - * drm_gem_vram_fill_create_dumb() - \
> -	Helper for implementing &struct drm_driver.dumb_create
> + * drm_gem_vram_fill_create_dumb() - Helper for implementing
> + *				     &struct drm_driver.dumb_create
> + *
>   * @file:		the DRM file
>   * @dev:		the DRM device
>   * @pg_align:		the buffer's alignment in multiples of the page size
>   * @pitch_align:	the scanline's alignment in powers of 2
> - * @args:		the arguments as provided to \
> -				&struct drm_driver.dumb_create
> + * @args:		the arguments as provided to
> + *			&struct drm_driver.dumb_create
>   *
>   * This helper function fills &struct drm_mode_create_dumb, which is used

The change to the description line is fine, it handles that.  But the
same is not true within the arguments; kernel-doc seems to simply drop
the continuation lines entirely, for some strange reason.

I think it's fair to call that a bug, and it shouldn't be *that* hard to
fix.  But it involves wading fairly deep into the Perl swamp, I may not
get there right away.

Thanks,

jon

Re: [RFC PATCH 0/2] kernel-doc: Do not pre-process comments

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
>
>> this is a RFC as I'm not quite sure if this change has some subtle side
>> effect.
>
> Turns out it does, unfortunately.  Consider a hunk like this:

Actually, I respectfully suggest that you ignore me completely...I'm
having kind of a scattered day.  In truth, this all seems good.

There is, however, one subtle little change.  Consider this from the
comment-cleanup patch:

> /**
> - * drm_gem_vram_plane_helper_prepare_fb() - \
> - *	Implements &struct drm_plane_helper_funcs.prepare_fb
> + * drm_gem_vram_plane_helper_prepare_fb() - Implements &struct
> + *					    drm_plane_helper_funcs.prepare_fb

Current kernel-doc preserves the "*" on the continuation line, with the
result that the description is rendered as an itemized list.  You can
see it at:

  https://docs.kernel.org/gpu/drm-mm.html?highlight=drm_gem_vram_plane_helper_prepare_fb#c.drm_gem_vram_plane_helper_prepare_fb

It's a subtle thing that doesn't really affect the readability, but even
so, somebody clearly ran into it at some point:

> /**
> - * drm_gem_vram_driver_dumb_create() - \
> -	Implements &struct drm_driver.dumb_create
> + * drm_gem_vram_driver_dumb_create() - Implements &struct drm_driver.dumb_create

A number of the existing comments leave out the leading "*" on the
continuation lines, presumably to work around this weirdness.  With your
patch, this little problem goes away - a little unadvertised extra
benefit! :)

The kernel-doc change should really go together with the DRM change.
I'm happy to carry both with an ack from DRMland or have the kernel-doc
patch go through the DRM tree, whichever is easiest.

Thanks,

jon