Re: [PATCH v4 2/2] rust: add dma coherent allocator abstraction.

[Abdiel Janulgue <abdiel.janulgue@gmail.com>]

On 05/11/2024 13:23, Miguel Ojeda wrote:
> Hi Abdiel,
> 
> Some quick comments on the docs I noticed.
> 
> On Tue, Nov 5, 2024 at 11:47 AM Abdiel Janulgue
> <abdiel.janulgue@gmail.com> wrote:
>>
>> +/// Abstraction of dma_alloc_coherent
>> +///
>> +/// # Invariants
>> +///
>> +/// For the lifetime of an instance of CoherentAllocation, the cpu address is a valid pointer
>> +/// to an allocated region of consistent memory and we hold a reference to the device.
> 
> Please use Markdown formatting everywhere (including documentation
> like here, as well as comments). For documentation, also please use
> intra-doc links where applicable (i.e. the square brackets, e.g.
> [`Foo`]).
> 
> Also, ideally, please define/explain the abstraction, rather than just
> saying it is an abstraction of something else.
> 
> Finally, if you want to have a link to a C header to refer to it, you
> can use a `srctree/...` link (please refer to others to see how it is
> usually done).
> 
>> +    /// # fn dox(dev: &Device) -> Result<()> {
> 
> Can we avoid this, i.e. use the `# Ok::<(), ...>(())` approach instead?
> 
> I see we got another `dox()` function in `page.rs`, which I guess is
> where you got it from, 

Yep, just learning it from existing code. But will update it.

Regards,
Abdiel