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
