Re: [PATCH 3/3] rust: dma: add as_slice/write functions for CoherentAllocation
From: Miguel Ojeda
Date: Thu Mar 27 2025 - 19:39:20 EST
Few doc nits...
On Wed, Mar 26, 2025 at 9:13 PM Abdiel Janulgue
<abdiel.janulgue@xxxxxxxxx> wrote:
>
> + /// Due to the safety requirements of slice, the caller should consider that the region could
Which requirements in particular? Link?
> + /// be modified by the device at anytime. For ringbuffer type of r/w access or use-cases where
at anytime -> "at any time" or "anytime"
> + /// the pointer to the live data is needed, `start_ptr()` or `start_ptr_mut()` could be
Intra-doc links where possible.
> + /// Writes data to the region starting from `offset`. `offset` is in units of `T`, not the
> + /// number of bytes.
I would double-check how it looks in the rendered docs (same for the
other method) -- the second sentence may be best in another paragraph,
i.e. outside the title, since it is special in the rendered
documentation ("short description"), unless you want to e.g.
differentiate from another variant.
> + // SAFETY:
> + // - The pointer is valid due to type invariant on `CoherentAllocation`
> + // and we've just checked that the range and index is within bounds.
Please indent the comments as you would the docs -- the docs ones are
correct, and Clippy should check those, but it doesn't check normal
comments, sadly.
Thanks!
Cheers,
Miguel