* [PATCH] rust: lock: Add intra-doc links to the Backend trait
@ 2023-05-07 15:22 Ben Gooding
2023-05-07 15:29 ` Alice Ryhl
2023-05-08 20:54 ` [PATCH] rust: lock: Add intra-doc links to the Backend trait Miguel Ojeda
0 siblings, 2 replies; 9+ messages in thread
From: Ben Gooding @ 2023-05-07 15:22 UTC (permalink / raw)
Cc: ben.gooding.dev, Benno Lossin, Miguel Ojeda, Alex Gaynor,
Wedson Almeida Filho, Boqun Feng, Gary Guo, Björn Roy Baron,
Martin Rodriguez Reboredo, rust-for-linux, linux-kernel
Also fix a minor typo in one of the comments
Suggested-by: Benno Lossin <benno.lossin@proton.me>
Link: https://lore.kernel.org/rust-for-linux/94625fe6-b87a-a8f0-5b2a-a8152d5f7436@proton.me/
Link: https://github.com/Rust-for-Linux/linux/issues/1001
Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
---
rust/kernel/sync/lock.rs | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index a2216325632d..95466201dab7 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -72,7 +72,7 @@ pub unsafe trait Backend {
/// A mutual exclusion primitive.
///
-/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock backend
+/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock [backend](Backend)
/// specified as the generic parameter `B`.
#[pin_data]
pub struct Lock<T: ?Sized, B: Backend> {
@@ -90,7 +90,7 @@ pub struct Lock<T: ?Sized, B: Backend> {
pub(crate) data: UnsafeCell<T>,
}
-// SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can.
+// SAFETY: `Lock` can be transferred across thread boundaries if the data it protects can.
unsafe impl<T: ?Sized + Send, B: Backend> Send for Lock<T, B> {}
// SAFETY: `Lock` serialises the interior mutability it provides, so it is `Sync` as long as the
@@ -126,7 +126,7 @@ impl<T: ?Sized, B: Backend> Lock<T, B> {
/// A lock guard.
///
-/// Allows mutual exclusion primitives that implement the `Backend` trait to automatically unlock
+/// Allows mutual exclusion primitives that implement the [`Backend`] trait to automatically unlock
/// when a guard goes out of scope. It also provides a safe and convenient way to access the data
/// protected by the lock.
#[must_use = "the lock unlocks immediately when the guard is unused"]
--
2.34.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] rust: lock: Add intra-doc links to the Backend trait
2023-05-07 15:22 [PATCH] rust: lock: Add intra-doc links to the Backend trait Ben Gooding
@ 2023-05-07 15:29 ` Alice Ryhl
2023-05-07 16:27 ` [PATCH] rust: lock: Reflow long documentation line Ben Gooding
2023-05-08 20:54 ` [PATCH] rust: lock: Add intra-doc links to the Backend trait Miguel Ojeda
1 sibling, 1 reply; 9+ messages in thread
From: Alice Ryhl @ 2023-05-07 15:29 UTC (permalink / raw)
To: Ben Gooding
Cc: Benno Lossin, Miguel Ojeda, Alex Gaynor, Wedson Almeida Filho,
Boqun Feng, Gary Guo, Björn Roy Baron,
Martin Rodriguez Reboredo, rust-for-linux, linux-kernel
On 5/7/23 17:22, Ben Gooding wrote:
> Also fix a minor typo in one of the comments
>
> Suggested-by: Benno Lossin <benno.lossin@proton.me>
> Link: https://lore.kernel.org/rust-for-linux/94625fe6-b87a-a8f0-5b2a-a8152d5f7436@proton.me/
> Link: https://github.com/Rust-for-Linux/linux/issues/1001
> Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
> ---
> -/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock backend
> +/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock [backend](Backend)
This line is too long. Please reflow at 100 characters.
You can also consider this option:
/// Exposes one of the kernel locking primitives. Which one is exposed
depends on the lock [backend]
/// specified as the generic parameter `B`.
///
/// [backend]: Backend
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH] rust: lock: Reflow long documentation line
2023-05-07 15:29 ` Alice Ryhl
@ 2023-05-07 16:27 ` Ben Gooding
2023-05-08 20:37 ` Miguel Ojeda
0 siblings, 1 reply; 9+ messages in thread
From: Ben Gooding @ 2023-05-07 16:27 UTC (permalink / raw)
To: alice
Cc: alex.gaynor, ben.gooding.dev, benno.lossin, bjorn3_gh,
boqun.feng, gary, linux-kernel, ojeda, rust-for-linux, wedsonaf,
yakoyoku
Suggested-by: Alice Ryhl <alice@ryhl.io>
Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
---
rust/kernel/sync/lock.rs | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 95466201dab7..04413f6f145a 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -72,8 +72,10 @@ pub unsafe trait Backend {
/// A mutual exclusion primitive.
///
-/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock [backend](Backend)
-/// specified as the generic parameter `B`.
+/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock
+/// [backend] specified as the generic parameter `B`.
+///
+/// [backend]: Backend
#[pin_data]
pub struct Lock<T: ?Sized, B: Backend> {
/// The kernel lock object.
--
2.34.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] rust: lock: Reflow long documentation line
2023-05-07 16:27 ` [PATCH] rust: lock: Reflow long documentation line Ben Gooding
@ 2023-05-08 20:37 ` Miguel Ojeda
2023-05-09 20:39 ` Ben Gooding
0 siblings, 1 reply; 9+ messages in thread
From: Miguel Ojeda @ 2023-05-08 20:37 UTC (permalink / raw)
To: Ben Gooding
Cc: alice, alex.gaynor, benno.lossin, bjorn3_gh, boqun.feng, gary,
linux-kernel, ojeda, rust-for-linux, wedsonaf, yakoyoku
Hi Ben,
On Sun, May 7, 2023 at 6:27 PM Ben Gooding <ben.gooding.dev@gmail.com> wrote:
>
> Suggested-by: Alice Ryhl <alice@ryhl.io>
> Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
Thanks for the patch! Several notes:
- Missing commit message -- in general, please check your patches
with `scripts/checkpatch.pl` and please read
https://docs.kernel.org/process/submitting-patches.html.
- This patch goes on top of the previous one you sent but, in the
kernel workflow, what you are expected to do is send a v2 of your
patch series instead. You can use `-v2` in `git format-patch` for
that.
- This patch is not just reflowing as the title implies, but it also
changes the style of the link -- is there a reason for that? If yes,
this should be explained.
Cheers,
Miguel
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] rust: lock: Add intra-doc links to the Backend trait
2023-05-07 15:22 [PATCH] rust: lock: Add intra-doc links to the Backend trait Ben Gooding
2023-05-07 15:29 ` Alice Ryhl
@ 2023-05-08 20:54 ` Miguel Ojeda
2023-05-09 20:23 ` [PATCH v2] " Ben Gooding
2023-05-15 17:59 ` [PATCH] " Andreas Hindborg
1 sibling, 2 replies; 9+ messages in thread
From: Miguel Ojeda @ 2023-05-08 20:54 UTC (permalink / raw)
To: Ben Gooding
Cc: Benno Lossin, Miguel Ojeda, Alex Gaynor, Wedson Almeida Filho,
Boqun Feng, Gary Guo, Björn Roy Baron,
Martin Rodriguez Reboredo, rust-for-linux, linux-kernel
On Sun, May 7, 2023 at 5:23 PM Ben Gooding <ben.gooding.dev@gmail.com> wrote:
>
> Also fix a minor typo in one of the comments
"iff" is not a typo. Even if it were, it is best to avoid mixing
different types of changes in commits, to keep them as small as
possible (though sometimes there are exceptions).
> -/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock backend
> +/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock [backend](Backend)
What about simply:
[`Backend`]
? (assuming it works).
Cheers,
Miguel
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v2] rust: lock: Add intra-doc links to the Backend trait
2023-05-08 20:54 ` [PATCH] rust: lock: Add intra-doc links to the Backend trait Miguel Ojeda
@ 2023-05-09 20:23 ` Ben Gooding
2023-07-19 19:59 ` Miguel Ojeda
2023-05-15 17:59 ` [PATCH] " Andreas Hindborg
1 sibling, 1 reply; 9+ messages in thread
From: Ben Gooding @ 2023-05-09 20:23 UTC (permalink / raw)
To: miguel.ojeda.sandonis
Cc: alex.gaynor, ben.gooding.dev, benno.lossin, bjorn3_gh,
boqun.feng, gary, linux-kernel, ojeda, rust-for-linux, wedsonaf,
yakoyoku
Add missing intra-doc links to the Backend trait to make navigating the
documentation easier.
Suggested-by: Benno Lossin <benno.lossin@proton.me>
Link: https://lore.kernel.org/rust-for-linux/94625fe6-b87a-a8f0-5b2a-a8152d5f7436@proton.me/
Link: https://github.com/Rust-for-Linux/linux/issues/1001
Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
---
rust/kernel/sync/lock.rs | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index a2216325632d..05ac8107ff3c 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -72,8 +72,8 @@ pub unsafe trait Backend {
/// A mutual exclusion primitive.
///
-/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock backend
-/// specified as the generic parameter `B`.
+/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock
+/// [`Backend`] specified as the generic parameter `B`.
#[pin_data]
pub struct Lock<T: ?Sized, B: Backend> {
/// The kernel lock object.
@@ -126,7 +126,7 @@ impl<T: ?Sized, B: Backend> Lock<T, B> {
/// A lock guard.
///
-/// Allows mutual exclusion primitives that implement the `Backend` trait to automatically unlock
+/// Allows mutual exclusion primitives that implement the [`Backend`] trait to automatically unlock
/// when a guard goes out of scope. It also provides a safe and convenient way to access the data
/// protected by the lock.
#[must_use = "the lock unlocks immediately when the guard is unused"]
--
2.34.1
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] rust: lock: Reflow long documentation line
2023-05-08 20:37 ` Miguel Ojeda
@ 2023-05-09 20:39 ` Ben Gooding
0 siblings, 0 replies; 9+ messages in thread
From: Ben Gooding @ 2023-05-09 20:39 UTC (permalink / raw)
To: Miguel Ojeda
Cc: alice, alex.gaynor, benno.lossin, bjorn3_gh, boqun.feng, gary,
linux-kernel, ojeda, rust-for-linux, wedsonaf, yakoyoku
Hi Miguel,
On 08/05/2023 21:37, Miguel Ojeda wrote:
> Hi Ben,
>
> On Sun, May 7, 2023 at 6:27 PM Ben Gooding <ben.gooding.dev@gmail.com> wrote:
>> Suggested-by: Alice Ryhl <alice@ryhl.io>
>> Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
> Thanks for the patch! Several notes:
>
> - Missing commit message -- in general, please check your patches
> with `scripts/checkpatch.pl` and please read
> https://docs.kernel.org/process/submitting-patches.html.
>
> - This patch goes on top of the previous one you sent but, in the
> kernel workflow, what you are expected to do is send a v2 of your
> patch series instead. You can use `-v2` in `git format-patch` for
> that.
>
> - This patch is not just reflowing as the title implies, but it also
> changes the style of the link -- is there a reason for that? If yes,
> this should be explained.
>
> Cheers,
> Miguel
Thank you very much for your feedback, this is really helpful as I'm
learning the process.
I've submitted a proper v2 of my patch based on your feedback which is
hopefully much more like what you would expect - please let me know.
Many thanks,
Ben
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] rust: lock: Add intra-doc links to the Backend trait
2023-05-08 20:54 ` [PATCH] rust: lock: Add intra-doc links to the Backend trait Miguel Ojeda
2023-05-09 20:23 ` [PATCH v2] " Ben Gooding
@ 2023-05-15 17:59 ` Andreas Hindborg
1 sibling, 0 replies; 9+ messages in thread
From: Andreas Hindborg @ 2023-05-15 17:59 UTC (permalink / raw)
To: Miguel Ojeda
Cc: Ben Gooding, Benno Lossin, Miguel Ojeda, Alex Gaynor,
Wedson Almeida Filho, Boqun Feng, Gary Guo, Björn Roy Baron,
Martin Rodriguez Reboredo, rust-for-linux, linux-kernel
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> writes:
> On Sun, May 7, 2023 at 5:23 PM Ben Gooding <ben.gooding.dev@gmail.com> wrote:
>>
>> Also fix a minor typo in one of the comments
>
> "iff" is not a typo. Even if it were, it is best to avoid mixing
> different types of changes in commits, to keep them as small as
> possible (though sometimes there are exceptions).
We should change the wording to "if and only if" to avoid confusion.
BR Andreas
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH v2] rust: lock: Add intra-doc links to the Backend trait
2023-05-09 20:23 ` [PATCH v2] " Ben Gooding
@ 2023-07-19 19:59 ` Miguel Ojeda
0 siblings, 0 replies; 9+ messages in thread
From: Miguel Ojeda @ 2023-07-19 19:59 UTC (permalink / raw)
To: Ben Gooding
Cc: alex.gaynor, benno.lossin, bjorn3_gh, boqun.feng, gary,
linux-kernel, ojeda, rust-for-linux, wedsonaf, yakoyoku
On Tue, May 9, 2023 at 10:24 PM Ben Gooding <ben.gooding.dev@gmail.com> wrote:
>
> Add missing intra-doc links to the Backend trait to make navigating the
> documentation easier.
>
> Suggested-by: Benno Lossin <benno.lossin@proton.me>
> Link: https://lore.kernel.org/rust-for-linux/94625fe6-b87a-a8f0-5b2a-a8152d5f7436@proton.me/
> Link: https://github.com/Rust-for-Linux/linux/issues/1001
> Signed-off-by: Ben Gooding <ben.gooding.dev@gmail.com>
Applied to `rust-next` -- thanks!
Cheers,
Miguel
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2023-07-19 19:59 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-05-07 15:22 [PATCH] rust: lock: Add intra-doc links to the Backend trait Ben Gooding
2023-05-07 15:29 ` Alice Ryhl
2023-05-07 16:27 ` [PATCH] rust: lock: Reflow long documentation line Ben Gooding
2023-05-08 20:37 ` Miguel Ojeda
2023-05-09 20:39 ` Ben Gooding
2023-05-08 20:54 ` [PATCH] rust: lock: Add intra-doc links to the Backend trait Miguel Ojeda
2023-05-09 20:23 ` [PATCH v2] " Ben Gooding
2023-07-19 19:59 ` Miguel Ojeda
2023-05-15 17:59 ` [PATCH] " Andreas Hindborg
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.