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

[Anna-Maria Behnsen]

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