Re: [WIP RFC v2 33/35] WIP: rust: drm/kms: Add VblankSupport

[Simona Vetter <simona.vetter@ffwll.ch>]

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@ffwll.ch> 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