Re: [PATCH v12 1/1] rust: interop: Add list module for C linked list interface

[Joel Fernandes]

On Thu, 12 Mar 2026 20:16:00 +0100, Miguel Ojeda wrote:
>> Acked-by: Miguel Ojeda <miguel.ojeda.sandonis@xxxxxxxxx>
>
> Acked-by: Miguel Ojeda <ojeda@xxxxxxxxxx>

Thanks, will change to this.

>> +//! # // SAFETY: head and all the items are test objects allocated in this scope.
>
> `head`

Fixed.

>> +//! // Rust wrapper for the C struct.
>
> Empty newline comment between these:
>
>   //! //
>
> Actually, should this be `//! ///`?
>
>> +//! // The list item struct in this example is defined in C code as:
>> +//! //   struct SampleItemC {
>> +//! //       int value;
>> +//! //       struct list_head link;
>> +//! //   };
>> +//! //
>
> Let's try to use the usual style, i.e. no empty newline at the end of
> docs for an item.
>
> And the example should be in a proper code block with a C tag, so all
> together something like:
>
>     //! /// Rust wrapper for the C struct.
>     //! ///
>     //! /// The list item struct in this example is defined in C code as:
>     //! ///
>     //! /// ```c
>     //! /// struct SampleItemC {
>     //! ///     int value;
>     //! ///     struct list_head link;
>     //! /// };
>     //! /// ```

Fixed.

>> +//!         // SAFETY: [`Item`] has same layout as [`SampleItemC`].
>
> No need for intra-doc links in comments (for now at least).

Fixed.

>> +//! // Create typed [`CList`] from sentinel head.
>
> Empty newline comment.

Fixed.

>> +//! // SAFETY: head is valid and initialized, items are `SampleItemC` with
>
> `head`
>
> However, this is giving me a Clippy issue (please see the other email).

Fixed.

>> +///   `next`/`prev` pointers are valid and non-NULL.
>
> We started using `NULL` recently as a convention for the null pointer.

Fixed.

>> +        // - [`CListHead`] has same layout as `list_head`.
>
> Intra-doc link not needed.

Fixed.

>> +        // - `ptr` is valid and unmodified for 'a per caller guarantees.
>
> `'a`

Fixed.

>> +        // SAFETY: self.as_raw() is valid per type invariants.
>
> `self.as_raw()`

Fixed.

>> +/// perform conversion of returned [`CListHead`] to an item (using `container_of` macro or similar).
>
> Intra-doc link to `container_of`?

Added.

>> +        // - [`CList`] has same layout as [`CListHead`] due to repr(transparent).
>
> Intra-doc link not needed.

>> +        // Convert to item using OFFSET.
>
> `OFFSET`
>
> Newline comment after this one.

>> +/// Create a C doubly-circular linked list interface `CList` from a raw `list_head` pointer.
>
> [`CList`]

>> +///   pointing to a list that is not concurrently modified for the lifetime of the `CList`.
>
> [`CList`]

Fixed all these.

>> +/// Refer to the examples in this module's documentation.
>
> Perhaps we could have an intra-doc link here to the module.

Added.

>> +        // Compile-time check that field path is a list_head.
>
> `list_head`

Fixed.

Thanks for the thorough review!

--
Joel Fernandes