On Tue, Jan 14, 2025 at 3:24 PM Simona Vetter <simona.vetter@xxxxxxxx> wrote: > > Feels like trying to replicate docs in rust might be dangerous, because if > we have to keep really detailed and nuanced docs around in two places we > will fail. > > Imo would be better to just explain how this maps to the C side and link > to that for full docs? Or somehow include that, but then all the > hyperlinks need to work from the C side kerneldoc or it's again > incomplete. Yeah, if things would be duplicated (in a way that does not add much value, e.g. things that do not require linking to many Rust-side things or does not use the examples KUnit support etc.), then I would say it is best to do it in a single place. To do that, we already support the `srctree/` links that can point to files (and in rust.docs.kernel.org get rendered to git.kernel.org). To point to rendered docs instead of files, for the time being the best so far is to link to docs.kernel.org directly. Then, what I proposed to upstream Rust is to have a feature that would give us a way to have a bibliography/map of links that could be used similarly to the existing intradoc-links in Rust docs. That way, projects could write something like [`struct my_struct`] and you would automatically get a link to the suitable URL to the C item, or something like [`ref:interleaved_replies`] to get a link to the Documentation/ rST reference and so on. It would also help to have common links without having to repeat them everywhere. With that in place, we could replace the docs.kernel.org links (though that requires rendering the docs, and we heard from at least someone that didn't want that at all...). Then we can also work on the other direction somehow, e.g. sharing a way to render docs properly for both C and Rust. I would like to work on some of that after the build system stuff. Cheers, Miguel
