[RFC PATCH] rust: types: extend `Opaque` documentation

[Dirk Behme <dirk.behme@de.bosch.com>]

In the discussion linked below some `Opaque` documentation
updates have been proposed. Add them.

Suggested-by: Daniel Almeida <daniel.almeida@collabora.com>
Link: https://lore.kernel.org/rust-for-linux/F8AB1160-F8CF-412F-8B88-4C79D65B53A1@collabora.com/
Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>

---

This is marked as RFC as it mainly takes some statements from
the linked discussion. Let us take this as a starting point
to discuss how we want to extend the `Opaque` documentation.

In that discussion it was mentioned

"Because `Opaque` implies the value may not be initialized,
 it's similar to `MaybeUninit`."

I wonder if we want to add some explanation for the *difference*
between `Opaque` and `MaybeUninit`?
---
 rust/kernel/types.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index 994e504ca9075..a2d78a39a9b14 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -244,6 +244,13 @@ fn drop(&mut self) {
 /// Using `Opaque<T>` allows to continue to use references on the Rust side even for values shared
 /// with C.
 ///
+/// An `Opaque<T>` means that "this is a blob of bytes and don't touch it". It *might* or
+/// *might not* contain a valid `T`. By dereferencing a raw pointer to the inner value, you
+/// are unsafely asserting that it does in fact contain a valid `T` *right now*. As `T` can
+/// be uninitialized, no meaningful action can be performed when `T` is dropped. This means
+/// the destructor of `Opaque<T>` does *not* run the destructor of `T` as that can't work
+/// on potentially invalid `T` data.
+///
 /// # Examples
 ///
 /// ```
-- 
2.48.0