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

[Miguel Ojeda]

On Thu, Mar 25, 2021 at 11:18 PM Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote:
>
> 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?

Yeah, I reached out to Jonathan a few weeks ago to discuss how we will
approach this, because I knew using `rustdoc` and Markdown could be
contentious ;-)

This is the solution we decided to go for the RFC but, of course,
nothing is set in stone:

  1. The "out-of-line" docs in `Documentation/rust/`: these will be in
RST as usual [*]. However, please note this does not include APIs or
anything like that, as it is done in the C side. Only a few "general
documents" that don't fit anywhere else are kept here.

  2. The "inline" docs in Rust source files: these will be parsed by
`rustdoc` and written in Markdown. These will contain the majority of
the Rust documentation. `rustdoc` is designed for Rust code, and
internally uses the Rust compiler, which comes with a number of
advantages.

The generated HTML docs will be showcased in the RFC. It is my hope
that this way we get feedback on them and see if people agree this
approach is worth keeping. We have put an effort (and I have been
annoying contributors enough to that end :-) to provide high-quality
documentation from the get-go.

Please note that we chose this way knowing well that inconsistency and
adding "yet one more tool" needs to come with big advantages to
offset. We think it is the best approach nevertheless!

[*] I discussed with Jonathan using Markdown since Sphinx supports it.
The main advantage would be easier refactoring of comments between the
out- and inline docs. But this is very minor, thus mixing two formats
inside `Documentation/` does not seem like worth it.

Cheers,
Miguel