Re: [PATCH v2 2/3] device: rust: expand documentation for Device

[Alice Ryhl <aliceryhl@google.com>]

On Tue, Jul 22, 2025 at 05:00:00PM +0200, Danilo Krummrich wrote:
> The documentation for the generic Device type is outdated and deserves
> much more detail.
> 
> Hence, expand the documentation and cover topics such as device types,
> device contexts, as well as information on how to use the generic device
> infrastructure to implement bus and class specific device types.
> 
> Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>

A few nits below, but in general looks good.

Reviewed-by: Alice Ryhl <aliceryhl@google.com>

> -/// This structure represents the Rust abstraction for a C `struct device`. This implementation
> -/// abstracts the usage of an already existing C `struct device` within Rust code that we get
> -/// passed from the C side.
> +/// This structure represents the Rust abstraction for a C `struct device`. A [`Device`] can either
> +/// exist as temporary reference (see also [`Device::from_raw`]), which is only valid within a
> +/// certain scope or as [`ARef<Device>`], owning a dedicated reference count.

Doesn't there need to be a comma between "scope" and "or"?

It's possible that I'm confusing the danish and english comma rules, but
I got confused when reading this.

> +/// # Implementing Class Devices
> +///
> +/// Class device implementations require less infrastructure and depend slightly more on the
> +/// specific subsystem.
> +///
> +/// An example implementation for a class device could look like this.
> +///
> +/// ```ignore
> +/// #[repr(C)]
> +/// #[pin_data]
> +/// pub struct Device<T: class::Driver> {
> +///     dev: Opaque<bindings::class_device_type>,
> +///     #[pin]
> +///     data: T::Data,

Should the `dev` field not also be pinned?

Alice