Re: [PATCH] kernel-doc: better handle '::' sequences

[Matthew Wilcox]

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