On Fri, 27 Mar 2020 13:28:54 +0200 Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> 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
