On Thu, Mar 25, 2021 at 03:04:00PM -0600, Jonathan Corbet wrote: > Matthew Wilcox <willy@xxxxxxxxxxxxx> writes: > > 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
