On Fri, 27 Mar 2020 13:28:54 +0200
Jani Nikula [off-list ref] wrote:

IMHO the real problem is kernel-doc doing too much preprocessing on the
input, preventing us from doing what would be the sensible thing in
rst. The more we try to fix the problem by adding more kernel-doc
processing, the further we dig ourselves into this hole.

If kernel-doc didn't have its own notion of section headers, such as
"example:", we wouldn't have this problem to begin with. We could just
use the usual rst construct; "example::" followed by an indented block.

I'm not going to stand in the way of the patch, but I'm telling you,
this is going to get harder, not easier, on this path.

I agree with you in principle.  The problem, of course, is that this is a
legacy gift from before the RST days and it will be hard to change.

A quick grep shows that the pattern:

	* Example:

appears nearly 100 times in current kernels.  It is not inconceivable to
make a push to get rid of all of those, turning them into ordinary RST
syntax - especially since not all of those are actually kerneldoc
comments.

The same quick grep says that "returns?:" appears about 10,000 times.
*That* will be painful to change, and I can only imagine that some
resistance would have to be overcome at some point.

So what do folks think we should do? :)

I want to ponder on this for a bit.  Peter, that may mean that I hold this
patch past the 5.7 merge window, which perhaps makes sense at this point
anyway, sorry.  But I really would like to push things into a direction
that moves us away from gnarly perl hacks and toward something more
maintainable in the long term.

Thanks,

jon