On Tue, Jan 14, 2025 at 04:04:41PM +0100, Miguel Ojeda wrote: > 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...). Yeah I think something like [`struct my_struct`] in the rust doc to link to the C side would be best. Dropping full url is kinda nasty, because it also makes navigating the source code itself harder. And I fairly often read the kerneldoc in the sources itself, not the rendered form. But that's maybe more a developer/maintainer use-case, since generally when I read docs it's to make sure they still match the code, so best when that's all close together. > 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. Hm I guess the other direction might apply for when we implement helpers in rust that C drivers are expected to use, like the qr code generator we now have. I think at least medium term most of our referencing needs will go from rustdoc to kerneldoc though, and not the other direction. -Sima -- Simona Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
