* [PATCH 0/2] kernel-doc: Do not pre-process comments
@ 2024-01-22 9:31 Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments Anna-Maria Behnsen
` (3 more replies)
0 siblings, 4 replies; 6+ messages in thread
From: Anna-Maria Behnsen @ 2024-01-22 9:31 UTC (permalink / raw)
To: linux-doc
Cc: Daniel Vetter, Jonathan Corbet, Anna-Maria Behnsen, dri-devel,
Maxime Ripard, Matthew Wilcox, Thomas Zimmermann, David Airlie
Hi,
this is a repost of the RFC queue
https://lkml.kernel.org/r/20240116151456.48238-1-anna-maria@linutronix.de
Jonathan Corbet is fine with this change and mentioned in an answer the
following:
"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."
But back to the patchset: 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 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments
2024-01-22 9:31 [PATCH 0/2] kernel-doc: Do not pre-process comments Anna-Maria Behnsen
@ 2024-01-22 9:31 ` Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments Anna-Maria Behnsen
` (2 subsequent siblings)
3 siblings, 0 replies; 6+ messages in thread
From: Anna-Maria Behnsen @ 2024-01-22 9:31 UTC (permalink / raw)
To: linux-doc
Cc: Daniel Vetter, Jonathan Corbet, Jani Nikula, Anna-Maria Behnsen,
dri-devel, Maxime Ripard, Matthew Wilcox, Thomas Zimmermann,
David Airlie
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>
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:
--
2.39.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments
2024-01-22 9:31 [PATCH 0/2] kernel-doc: Do not pre-process comments Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments Anna-Maria Behnsen
@ 2024-01-22 9:31 ` Anna-Maria Behnsen
2024-01-23 7:00 ` Randy Dunlap
2024-01-25 18:14 ` [PATCH 0/2] kernel-doc: Do not pre-process comments Daniel Vetter
2024-01-30 20:13 ` Jonathan Corbet
3 siblings, 1 reply; 6+ messages in thread
From: Anna-Maria Behnsen @ 2024-01-22 9:31 UTC (permalink / raw)
To: linux-doc
Cc: Daniel Vetter, Jonathan Corbet, Anna-Maria Behnsen, dri-devel,
Maxime Ripard, Matthew Wilcox, Thomas Zimmermann, David Airlie
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments
2024-01-22 9:31 ` [PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments Anna-Maria Behnsen
@ 2024-01-23 7:00 ` Randy Dunlap
0 siblings, 0 replies; 6+ messages in thread
From: Randy Dunlap @ 2024-01-23 7:00 UTC (permalink / raw)
To: Anna-Maria Behnsen, linux-doc
Cc: Daniel Vetter, Jonathan Corbet, dri-devel, Maxime Ripard,
Matthew Wilcox, Thomas Zimmermann, David Airlie
On 1/22/24 01:31, Anna-Maria Behnsen wrote:
> 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>
I compared several hundred html files before and after this patch
and they were all the same, so I will say:
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Thanks.
> ---
> 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
--
#Randy
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] kernel-doc: Do not pre-process comments
2024-01-22 9:31 [PATCH 0/2] kernel-doc: Do not pre-process comments Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments Anna-Maria Behnsen
@ 2024-01-25 18:14 ` Daniel Vetter
2024-01-30 20:13 ` Jonathan Corbet
3 siblings, 0 replies; 6+ messages in thread
From: Daniel Vetter @ 2024-01-25 18:14 UTC (permalink / raw)
To: Anna-Maria Behnsen
Cc: Daniel Vetter, Jonathan Corbet, dri-devel, linux-doc,
Maxime Ripard, Matthew Wilcox, Thomas Zimmermann, David Airlie
On Mon, Jan 22, 2024 at 10:31:50AM +0100, Anna-Maria Behnsen wrote:
> Hi,
>
> this is a repost of the RFC queue
> https://lkml.kernel.org/r/20240116151456.48238-1-anna-maria@linutronix.de
>
> Jonathan Corbet is fine with this change and mentioned in an answer the
> following:
>
> "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."
Agree, that sounds like the simplest merge plan and I don't think we have
anything in-flight for vram helpers that would cause conflicts. For
merging the drm patch through Jon's -doc tree:
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
>
> But back to the patchset: 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 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
>
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] kernel-doc: Do not pre-process comments
2024-01-22 9:31 [PATCH 0/2] kernel-doc: Do not pre-process comments Anna-Maria Behnsen
` (2 preceding siblings ...)
2024-01-25 18:14 ` [PATCH 0/2] kernel-doc: Do not pre-process comments Daniel Vetter
@ 2024-01-30 20:13 ` Jonathan Corbet
3 siblings, 0 replies; 6+ messages in thread
From: Jonathan Corbet @ 2024-01-30 20:13 UTC (permalink / raw)
To: Anna-Maria Behnsen, linux-doc
Cc: Thomas Zimmermann, Anna-Maria Behnsen, dri-devel, Maxime Ripard,
Matthew Wilcox, Daniel Vetter, David Airlie
Anna-Maria Behnsen <anna-maria@linutronix.de> writes:
> Hi,
>
> this is a repost of the RFC queue
> https://lkml.kernel.org/r/20240116151456.48238-1-anna-maria@linutronix.de
>
> Jonathan Corbet is fine with this change and mentioned in an answer the
> following:
>
> "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."
>
> But back to the patchset: 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 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(-)
Series applied, thanks.
jon
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2024-01-30 20:13 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-01-22 9:31 [PATCH 0/2] kernel-doc: Do not pre-process comments Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 1/2] drm/vram-helper: Fix 'multi-line' kernel-doc comments Anna-Maria Behnsen
2024-01-22 9:31 ` [PATCH 2/2] scripts/kernel-doc: Do not process backslash lines in comments Anna-Maria Behnsen
2024-01-23 7:00 ` Randy Dunlap
2024-01-25 18:14 ` [PATCH 0/2] kernel-doc: Do not pre-process comments Daniel Vetter
2024-01-30 20:13 ` Jonathan Corbet
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).