Messages in this thread |  | | From | Miguel Ojeda <> | | Date | Thu, 12 Mar 2026 20:16:00 +0100 | | Subject | Re: [PATCH v12 1/1] rust: interop: Add list module for C linked list interface |
| |
On Fri, Mar 6, 2026 at 9:37 PM Joel Fernandes <joelagnelf@nvidia.com> wrote: > > Acked-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Acked-by: Miguel Ojeda <ojeda@kernel.org>
> +//! # // SAFETY: head and all the items are test objects allocated in this scope.
`head`
> +//! // 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; //! /// }; //! /// ```
> +//! // SAFETY: [`Item`] has same layout as [`SampleItemC`].
No need for intra-doc links in comments (for now at least).
> +//! // Create typed [`CList`] from sentinel head.
Empty newline comment.
> +//! // SAFETY: head is valid and initialized, items are `SampleItemC` with
`head`
However, this is giving me a Clippy issue (please see the other email).
> +/// `next`/`prev` pointers are valid and non-NULL.
We started using `NULL` recently as a convention for the null pointer.
> + // - [`CListHead`] has same layout as `list_head`.
Intra-doc link not needed.
> + // - `ptr` is valid and unmodified for 'a per caller guarantees.
`'a`
> + // SAFETY: self.as_raw() is valid per type invariants.
`self.as_raw()`
> +/// perform conversion of returned [`CListHead`] to an item (using `container_of` macro or similar).
Intra-doc link to `container_of`?
> + // - [`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`]
> +/// Refer to the examples in this module's documentation.
Perhaps we could have an intra-doc link here to the module.
> + // Compile-time check that field path is a list_head.
`list_head`
Cheers, Miguel
|  |