Received-SPF: pass (google.com: domain of linux-kernel+bounces-29631-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Precedence: bulk
MIME-Version: 1.0
References: <20240116160141.165951-1-kernel@valentinobst.de> <20240116231106.168864-1-kernel@valentinobst.de>
In-Reply-To: <20240116231106.168864-1-kernel@valentinobst.de>
From: Trevor Gross <tmgross@umich.edu>
Date: Wed, 17 Jan 2024 20:42:17 -0500
Message-ID: <CALNs47tWivxJhqjC-L8rLQKP420y1zCgCiHSZc5JPNbCVpwxgw@mail.gmail.com>
Subject: Re: [PATCH 10/13] rust: kernel: add doclinks
To: Valentin Obst <kernel@valentinobst.de>
Cc: Miguel Ojeda <ojeda@kernel.org>, Alex Gaynor <alex.gaynor@gmail.com>, 
	Wedson Almeida Filho <wedsonaf@gmail.com>, Boqun Feng <boqun.feng@gmail.com>, Gary Guo <gary@garyguo.net>, 
	=?UTF-8?Q?Bj=C3=B6rn_Roy_Baron?= <bjorn3_gh@protonmail.com>, 
	Benno Lossin <benno.lossin@proton.me>, Andreas Hindborg <a.hindborg@samsung.com>, 
	Alice Ryhl <aliceryhl@google.com>, rust-for-linux@vger.kernel.org, 
	linux-kernel@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tue, Jan 16, 2024 at 6:11=E2=80=AFPM Valentin Obst <kernel@valentinobst.=
de> wrote:
>
> Add doclinks to existing documentation.
>
> Signed-off-by: Valentin Obst <kernel@valentinobst.de>
> ---
>  rust/kernel/sync/arc.rs  |  6 +++---
>  rust/kernel/sync/lock.rs | 13 +++++++++---
>  rust/kernel/workqueue.rs | 45 ++++++++++++++++++++++++----------------
>  3 files changed, 40 insertions(+), 24 deletions(-)
>
> diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs
> index 6c46b1affca5..936bc549a082 100644
> --- a/rust/kernel/sync/arc.rs
> +++ b/rust/kernel/sync/arc.rs
> @@ -365,12 +365,12 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
>  /// A borrowed reference to an [`Arc`] instance.
>  ///
>  /// For cases when one doesn't ever need to increment the refcount on th=
e allocation, it is simpler
> -/// to use just `&T`, which we can trivially get from an `Arc<T>` instan=
ce.
> +/// to use just `&T`, which we can trivially get from an [`Arc<T>`] inst=
ance.
>  ///
>  /// However, when one may need to increment the refcount, it is preferab=
le to use an `ArcBorrow<T>`
>  /// over `&Arc<T>` because the latter results in a double-indirection: a=
 pointer (shared reference)
> -/// to a pointer (`Arc<T>`) to the object (`T`). An [`ArcBorrow`] elimin=
ates this double
> -/// indirection while still allowing one to increment the refcount and g=
etting an `Arc<T>` when/if
> +/// to a pointer ([`Arc<T>`]) to the object (`T`). An [`ArcBorrow`] elim=
inates this double
> +/// indirection while still allowing one to increment the refcount and g=
etting an [`Arc<T>`] when/if
>  /// needed.

I think it is usually okay to only link the first usage in a section
or paragraph. No harm having more of course.

>  /// # Invariants
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index 467249b39f71..f14179d19d4e 100644
> --- a/rust/kernel/sync/lock.rs
> +++ b/rust/kernel/sync/lock.rs
> @@ -21,14 +21,21 @@
>  /// # Safety
>  ///
>  /// - Implementers must ensure that only one thread/CPU may access the p=
rotected data once the lock
> -/// is owned, that is, between calls to `lock` and `unlock`.
> -/// - Implementers must also ensure that `relock` uses the same locking =
method as the original
> +/// is owned, that is, between calls to [`lock`] and [`unlock`].
> +/// - Implementers must also ensure that [`relock`] uses the same lockin=
g method as the original
>  /// lock operation.

The second lines of these list items should probably be indented
(doesn't have to be in this patch).

> [...]
> @@ -290,10 +294,11 @@ unsafe fn __enqueue<F>(self, queue_work_on: F) -> S=
elf::EnqueueOutput
>
>  /// Defines the method that should be called directly when a work item i=
s executed.
>  ///
> -/// This trait is implemented by `Pin<Box<T>>` and `Arc<T>`, and is main=
ly intended to be
> +/// This trait is implemented by `Pin<Box<T>>` and [`Arc<T>`], and is ma=
inly intended to be

`Pin` could be linked too.

> [...]

Just a few nits for this one, nothing blocking.

Reviewed-by: Trevor Gross <tmgross@umich.edu>