Re: [PATCH 2/2] rust: add hw_random module

[Miguel Ojeda]

Hi Manos,

Some quick doc nits I noticed while managing our list...

On Fri, May 29, 2026 at 5:50 PM Manos Pitsidianakis
<manos@xxxxxxxxxxxxxx> wrote:
>
> +//! # Example

"Examples" is the section name we use.

> +//!# fn no_run() {
> +//!# use kernel::hw_random::*;
> +//!# use kernel::str::CString;
> +//!# use kernel::prelude::*;

Missing indentation.

> +//!     fn read(&self, data: &mut Buffer<'_>, can_wait: bool) -> Result<()> {

-> Result

> +//!         // write zeroes - in your driver, this should write actual data from your hardware.

"Write"

> +//! let name = CString::try_from(c"example_hwrng").unwrap();

Could you avoid `unwrap()`s, perhaps using `?` etc.? It is not
critical, but good practice to try to show how "real code" would be
written.

> +        from_result,          //
> +        to_result,            //
> +        VTABLE_DEFAULT_ERROR, //

Please only use the slashes in the last one:

> +    },

...but add one here, since this level doesn't have it.

> +    /// Returns `true` if the buffer has been filled.

[`true`]

> +        // SAFETY: u8 and MaybeUninit<u8> have the same layout

Please use Markdown (but no intra-doc links needed) in comments too, e.g.

  `u8` ... `MaybeUninit<u8>`

There are other instances below.

> +/// [`struct hwrng`]: srctree/include/linux/hw_random.h

Is this reference used?

> +#[vtable]
> +/// Trait for the implementation of hardware RNGs.

Attributes after documentation.

Other instances below too.

> +    /// [`hwrng_unregister`]: srctree/include/linux/hw_random.h
> +    #[inline]
> +    #[doc(alias = "hwrng_unregister")]

Is this one for the alias? How does it behave when rendered?

> +    pub fn unregister(&self) {
> +        if self
> +            .registered
> +            .compare_exchange(true, false, Ordering::SeqCst, Ordering::Acquire)
> +            .is_ok()

We are starting to add `// ORDERING: ...` comments for things like
this, so it would be nice to have them here already.

> +        // SAFETY: we set `priv_` as the value of `*mut Self` when initializing.

Please start comments capitalized. Other instances elsewhere too.

Cheers,
Miguel