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

[Jonathan Corbet <corbet@lwn.net>]

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