Message-ID: <Z4aFBhzyBrq48aib@phenom.ffwll.local>
Date: Tue, 14 Jan 2025 16:38:46 +0100
From: Simona Vetter <simona.vetter@...ll.ch>
To: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
Cc: Lyude Paul <lyude@...hat.com>,
	Daniel Almeida <daniel.almeida@...labora.com>,
	dri-devel@...ts.freedesktop.org, rust-for-linux@...r.kernel.org,
	Asahi Lina <lina@...hilina.net>, Danilo Krummrich <dakr@...nel.org>,
	mcanal@...lia.com, airlied@...hat.com, zhiw@...dia.com,
	cjia@...dia.com, jhubbard@...dia.com,
	Miguel Ojeda <ojeda@...nel.org>,
	Alex Gaynor <alex.gaynor@...il.com>,
	Wedson Almeida Filho <wedsonaf@...il.com>,
	Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>,
	Björn Roy Baron <bjorn3_gh@...tonmail.com>,
	Benno Lossin <benno.lossin@...ton.me>,
	Andreas Hindborg <a.hindborg@...sung.com>,
	Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>,
	Danilo Krummrich <dakr@...hat.com>,
	Mika Westerberg <mika.westerberg@...ux.intel.com>,
	open list <linux-kernel@...r.kernel.org>
Subject: Re: [WIP RFC v2 33/35] WIP: rust: drm/kms: Add VblankSupport

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@...ll.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

Powered by blists - more mailing lists