On Thu, 12 Mar 2026 20:16:00 +0100, Miguel Ojeda wrote:
>> Acked-by: Miguel Ojeda <[email protected]>
>
> Acked-by: Miguel Ojeda <[email protected]>
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
