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@xxxxxxxxxxxxx > > 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@xxxxxxxx> > > 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
