rust: lock: Add intra-doc links to the Backend trait
Subsystems (3)
PATCH 1/1 rust: lock: Add intra-doc links to the Backend trait
Also fix a minor typo in one of the comments
--- rust/kernel/sync/lock.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
rust/kernel/sync/lock.rs +3 -3
@@ -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" ]
Signature · 1 line
2.34.1
rust/kernel/sync/lock.rs pub unsafe trait Backend { · line 75
Quoted 9 lines · Ben Gooding
Also fix a minor typo in one of the comments
Suggested-by Benno Lossin <[email protected]>Signed-off-by Ben Gooding <[email protected]>---
rust/kernel/sync/lock.rs +1
-1-/// 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
PATCH 1/1 rust: lock: Reflow long documentation line
--- rust/kernel/sync/lock.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
rust/kernel/sync/lock.rs +4 -2
@@ -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.
Signature · 1 line
2.34.1
Re: [PATCH] rust: lock: Reflow long documentation line
Hi Ben,
Quoted 3 lines · Ben Gooding
Suggested-by Alice Ryhl <[email protected]>Signed-off-by Ben Gooding <[email protected]>
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
Re: [PATCH] rust: lock: Reflow long documentation line
Hi Miguel,
Quoted 16 lines · Miguel Ojeda
Hi Ben,
Quoted 2 lines · Ben Gooding
Suggested-by Alice Ryhl <[email protected]>Signed-off-by Ben Gooding <[email protected]>Thanks for the patch! Several notes:
- Missing commit message -- in general, please check your patches
withscripts/checkpatch.pland 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-v2ingit format-patchfor that.
Quoted 6 lines
- 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
Quoted 2 lines · Ben Gooding
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).
rust/kernel/sync/lock.rs pub unsafe trait Backend { · line 75
Quoted 2 lines
rust/kernel/sync/lock.rs +1
-1-/// 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
PATCH v2 1/1 rust: lock: Add intra-doc links to the Backend trait
Add missing intra-doc links to the Backend trait to make navigating the documentation easier.
--- rust/kernel/sync/lock.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
rust/kernel/sync/lock.rs +3 -3
@@ -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" ]
Signature · 1 line
2.34.1
Miguel Ojeda
AppliedQuoted 8 lines · Ben Gooding
Add missing intra-doc links to the Backend trait to make navigating the documentation easier.
Applied to rust-next -- thanks!
Cheers,
Miguel
Quoted 7 lines · Miguel Ojeda
Quoted 2 lines · Ben Gooding
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