On Fri, Mar 6, 2026 at 9:37 PM Joel Fernandes <[email protected]> wrote: > > Acked-by: Miguel Ojeda <[email protected]>
Acked-by: Miguel Ojeda <[email protected]> > +//! # // 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
