Commit cd1ed11a authored by Borys Tyran's avatar Borys Tyran Committed by Miguel Ojeda
Browse files

rust: improve lifetimes markup 

Improve lifetimes markup; e.g. from:

    /// ... 'a ...

to:

    /// ... `'a` ...

This will make lifetimes display as code span with Markdown and make it
more consistent with rest of the docs.

Link: https://github.com/Rust-for-Linux/linux/issues/1138


Signed-off-by: default avatarBorys Tyran <borys.tyran@protonmail.com>
Link: https://lore.kernel.org/r/20250207142437.112435-1-borys.tyran@protonmail.com


[ Reworded and changed Closes tag to Link. - Miguel ]
Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent fbefae55

rust/kernel/fs/file.rs

+2 −2
Original line number Diff line number Diff line
@@ -267,7 +267,7 @@ pub fn fget(fd: u32) -> Result<ARef<LocalFile>, BadFdError> { 
    /// # Safety

    ///

    /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is

    ///   positive for the duration of 'a.

    ///   positive for the duration of `'a`.

    /// * The caller must ensure that if there is an active call to `fdget_pos` that did not take

    ///   the `f_pos_lock` mutex, then that call is on the current thread.

    #[inline]
@@ -341,7 +341,7 @@ impl File { 
    /// # Safety

    ///

    /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is

    ///   positive for the duration of 'a.

    ///   positive for the duration of `'a`.

    /// * The caller must ensure that if there are active `fdget_pos` calls on this file, then they

    ///   took the `f_pos_lock` mutex.

    #[inline]

rust/kernel/rbtree.rs

+3 −3
Original line number Diff line number Diff line
@@ -886,7 +886,7 @@ fn get_neighbor_raw(&self, direction: Direction) -> Option<NonNull<bindings::rb_ 
    /// # Safety

    ///

    /// - `node` must be a valid pointer to a node in an [`RBTree`].

    /// - The caller has immutable access to `node` for the duration of 'b.

    /// - The caller has immutable access to `node` for the duration of `'b`.

    unsafe fn to_key_value<'b>(node: NonNull<bindings::rb_node>) -> (&'b K, &'b V) {

        // SAFETY: the caller guarantees that `node` is a valid pointer in an `RBTree`.

        let (k, v) = unsafe { Self::to_key_value_raw(node) };
@@ -897,7 +897,7 @@ unsafe fn to_key_value<'b>(node: NonNull<bindings::rb_node>) -> (&'b K, &'b V) { 
    /// # Safety

    ///

    /// - `node` must be a valid pointer to a node in an [`RBTree`].

    /// - The caller has mutable access to `node` for the duration of 'b.

    /// - The caller has mutable access to `node` for the duration of `'b`.

    unsafe fn to_key_value_mut<'b>(node: NonNull<bindings::rb_node>) -> (&'b K, &'b mut V) {

        // SAFETY: the caller guarantees that `node` is a valid pointer in an `RBTree`.

        let (k, v) = unsafe { Self::to_key_value_raw(node) };
@@ -908,7 +908,7 @@ unsafe fn to_key_value_mut<'b>(node: NonNull<bindings::rb_node>) -> (&'b K, &'b 
    /// # Safety

    ///

    /// - `node` must be a valid pointer to a node in an [`RBTree`].

    /// - The caller has immutable access to the key for the duration of 'b.

    /// - The caller has immutable access to the key for the duration of `'b`.

    unsafe fn to_key_value_raw<'b>(node: NonNull<bindings::rb_node>) -> (&'b K, *mut V) {

        // SAFETY: By the type invariant of `Self`, all non-null `rb_node` pointers stored in `self`

        // point to the links field of `Node<K, V>` objects.

rust/kernel/seq_file.rs

+1 −1
Original line number Diff line number Diff line
@@ -18,7 +18,7 @@ impl SeqFile { 
    ///

    /// # Safety

    ///

    /// The caller must ensure that for the duration of 'a the following is satisfied:

    /// The caller must ensure that for the duration of `'a` the following is satisfied:

    /// * The pointer points at a valid `struct seq_file`.

    /// * The `struct seq_file` is not accessed from any other thread.

    pub unsafe fn from_raw<'a>(ptr: *mut bindings::seq_file) -> &'a SeqFile {

rust/kernel/sync/poll.rs

+2 −2
Original line number Diff line number Diff line
@@ -43,11 +43,11 @@ impl PollTable { 
    ///

    /// # Safety

    ///

    /// The caller must ensure that for the duration of 'a, the pointer will point at a valid poll

    /// The caller must ensure that for the duration of `'a`, the pointer will point at a valid poll

    /// table (as defined in the type invariants).

    ///

    /// The caller must also ensure that the `poll_table` is only accessed via the returned

    /// reference for the duration of 'a.

    /// reference for the duration of `'a`.

    pub unsafe fn from_ptr<'a>(ptr: *mut bindings::poll_table) -> &'a mut PollTable {

        // SAFETY: The safety requirements guarantee the validity of the dereference, while the

        // `PollTable` type being transparent makes the cast ok.

rust/kernel/types.rs

+3 −3
Original line number Diff line number Diff line
@@ -77,7 +77,7 @@ unsafe fn try_from_foreign(ptr: *mut crate::ffi::c_void) -> Option<Self> { 
    ///

    /// The provided pointer must have been returned by a previous call to [`into_foreign`], and if

    /// the pointer is ever passed to [`from_foreign`], then that call must happen after the end of

    /// the lifetime 'a.

    /// the lifetime `'a`.

    ///

    /// [`into_foreign`]: Self::into_foreign

    /// [`from_foreign`]: Self::from_foreign
@@ -100,9 +100,9 @@ unsafe fn try_from_foreign(ptr: *mut crate::ffi::c_void) -> Option<Self> { 
    ///

    /// The provided pointer must have been returned by a previous call to [`into_foreign`], and if

    /// the pointer is ever passed to [`from_foreign`], then that call must happen after the end of

    /// the lifetime 'a.

    /// the lifetime `'a`.

    ///

    /// The lifetime 'a must not overlap with the lifetime of any other call to [`borrow`] or

    /// The lifetime `'a` must not overlap with the lifetime of any other call to [`borrow`] or

    /// `borrow_mut` on the same object.

    ///

    /// [`into_foreign`]: Self::into_foreign