On Thu, Mar 25, 2021 at 12:51:25PM -0600, Jonathan Corbet wrote: > Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> 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+huawei@xxxxxxxxxx> > > --- > > 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. https://blog.golang.org/godoc would be my preferred format ... the less information repeated from the actual function, the better. But if we're actually going to have rust in the kernel, perhaps rustdoc is better. https://doc.rust-lang.org/beta/rust-by-example/meta/doc.html (*) because nobody actually likes kernel-doc.pl, right?
