Matthew Wilcox <wi...@infradead.org> writes: > On Thu, Mar 25, 2021 at 12:51:25PM -0600, Jonathan Corbet wrote: >> Mauro Carvalho Chehab <mchehab+hua...@kernel.org> writes: >> >> > Right now, if one of the following headers end with a '::', the >> > kernel-doc script will do the wrong thing: >> > >> > description|context|returns?|notes?|examples? >> > >> > The real issue is with examples, as people could try to write >> > something like: >> > >> > example:: >> > >> > /* Some C code */ >> > >> > and this won't be properly evaluated. So, improve the regex >> > to not catch '\w+::' regex for the above identifiers. >> > >> > Signed-off-by: Mauro Carvalho Chehab <mchehab+hua...@kernel.org> >> > --- >> > scripts/kernel-doc | 2 +- >> > 1 file changed, 1 insertion(+), 1 deletion(-) >> >> Ah....wouldn't it be nice if kerneldoc comments had just been RST from >> the beginning? I don't think we're fixing that at this point, though, >> so this makes sense; applied. > > Well ... > > If somebody wants to write a new tool (*) that extracts documentation > written in a different format, I think that could be done. Because the > hard part of writing documentation is getting the person who knows the > code to get everything that's in their brain into words, not really > the formatting. > > If somebody did want to write such a tool, I think we'd also want a > tool that turns the existing kernel-doc into the new format, because > maintaining two function-doc formats would be awful.
Yeah, the thing is that, as long as we're documenting code with something other than RST, we *do* have two formats, and they interact with each other in surprising and unwelcome ways. I don't really see a fix, though. Even if we come up with the Perfect New Format™, I don't want to be the one trying to push through the patches changing tens of thousands of kerneldoc comments over... jon
