Re: [PATCH 1/3] device: rust: documentation for DeviceContext

["Benno Lossin" <lossin@kernel.org>]

On Fri Jul 18, 2025 at 3:14 PM CEST, Danilo Krummrich wrote:
> On Fri Jul 18, 2025 at 2:32 PM CEST, Alexandre Courbot wrote:
>> On Fri Jul 18, 2025 at 7:45 AM JST, Danilo Krummrich wrote:
>>> +///
>>> +/// Bus devices can automatically implement the dereference hierarchy by using
>>> +/// [`impl_device_context_deref`](kernel::impl_device_context_deref).
>>>  pub trait DeviceContext: private::Sealed {}
>>>  
>>> -/// The [`Normal`] context is the context of a bus specific device when it is not an argument of
>>> -/// any bus callback.
>>> +/// The [`Normal`] context is the default [`DeviceContext`] of any [`Device`].
>>> +///
>>> +/// The normal context does not indicate any specific scope. Any `Device<Ctx>` is also a valid
>>> +/// [`Device<Normal>`]. It is the only [`DeviceContext`] for which it is valid to implement
>>> +/// [`AlwaysRefCounted`](kernel::types::AlwaysRefCounted) for.
>>>  pub struct Normal;
>>
>> `Normal` as a name can be interpreted in many different ways, and in the
>> case of a device context it is not clear what the "normal" state is. I
>> think it would be helpful if we can elaborate a bit more on what this
>> implies (i.e. what concretely speaking are the limitations), and if
>> possible why this name has been chosen.
>
> It's the context that does not guarantee any specific scope. But that's also
> what the documentation says.
>
> I also wouldn't speak of limitations, it's just that it doesn't allow to make
> *additional* assumptions compared to other device context types.
>
> Yet, if you have suggestions on what to add specifically, please let me know
> (maybe simply my previous sentence?).
>
> Regarding the name, "Normal" seems reasonable for the device context that does
> not guarantee any specific scope. We could have also named it just "Default".
>
> I think "Normal" is fine, as in "it's just a normal device reference, no
> specific scope guaranteed".

Not sure if this helps, but `Plain` might carry a slightly different
meaning from `Normal` that is better in this case?

(but you probably can't infer much from the name anyways)

---
Cheers,
Benno