Re: [PATCH 0/2] kernel-doc: Do not pre-process comments
Anna-Maria Behnsen writes:
> Hi,
>
> this is a repost of the RFC queue
> https://lkml.kernel.org/r/20240116151456.48238-1-anna-ma...@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
Re: [PATCH 0/2] kernel-doc: Do not pre-process comments
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-ma...@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
>
> 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
[PATCH 0/2] kernel-doc: Do not pre-process comments
Hi,
this is a repost of the RFC queue
https://lkml.kernel.org/r/20240116151456.48238-1-anna-ma...@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
