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

[Jonathan Corbet <corbet@lwn.net>]

Jonathan Corbet <corbet@lwn.net> writes:

> 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:

Actually, I respectfully suggest that you ignore me completely...I'm
having kind of a scattered day.  In truth, this all seems good.

There is, however, one subtle little change.  Consider this from the
comment-cleanup patch:

> /**
> - * 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

Current kernel-doc preserves the "*" on the continuation line, with the
result that the description is rendered as an itemized list.  You can
see it at:

  https://docs.kernel.org/gpu/drm-mm.html?highlight=drm_gem_vram_plane_helper_prepare_fb#c.drm_gem_vram_plane_helper_prepare_fb

It's a subtle thing that doesn't really affect the readability, but even
so, somebody clearly ran into it at some point:

> /**
> - * drm_gem_vram_driver_dumb_create() - \
> -	Implements &struct drm_driver.dumb_create
> + * drm_gem_vram_driver_dumb_create() - Implements &struct drm_driver.dumb_create

A number of the existing comments leave out the leading "*" on the
continuation lines, presumably to work around this weirdness.  With your
patch, this little problem goes away - a little unadvertised extra
benefit! :)

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.

Thanks,

jon