On Thu, Mar 25, 2021 at 03:04:00PM -0600, Jonathan Corbet wrote:

Matthew Wilcox [off-list ref] writes:

quoted

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

I can't argue with either of your points.

The rust code is alredy coming though ...

rust/kernel/buffer.rs:/// A pre-allocated buffer that implements [`core::fmt::Write`].

so now we have three formats.  Markdown and RST are _very_ similar, but
not identical [1].  Oh, and even better we now have three distinct tools --
kerneldoc, rustdoc and sphinx.  Have the rust people reached out to you
about integrating the various docs?

[1] https://en.wikipedia.org/wiki/Lightweight_markup_language#Comparison_of_lightweight_markup_language_syntax