Skip to contentSkip to conversation

rust: sync: improve `Arc` documentation links

PATCH Superseded Harish-CS 4 participants 7 messages Jul 8 – Aug 10

Subsystems (2)
Rust Rust sync

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Harish-CS

author
#0 lore raw

PATCH 1/1 rust: sync: improve `Arc` documentation links

The Arc documentation has a few mentions that do not follow the surrounding style: a plain Arc without an intra-doc link and a lower-case "arc".

Use intra-doc links for rustdoc references to Arc and spell internal comments consistently as Arc, matching nearby docs.

Suggested-by Miguel Ojeda <[email protected]>
Link https://github.com/Rust-for-Linux/linux/issues/1240
Signed-off-by Harish-CS <[email protected]>
---
 rust/kernel/sync/arc.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
rust/kernel/sync/arc.rs +6 -6
index 5ac4961b7cd2..76a153e01283 100644
@@ -154,7 +154,7 @@ impl<T: ?Sized> ArcInner<T> {
     ///
     /// # Safety
     ///
-    /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the `Arc` must
+    /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the [`Arc`] must
     /// not yet have been destroyed.
     unsafe fn container_of(ptr: *const T) -> NonNull<ArcInner<T>> {
         let refcount_layout = Layout::new::<Refcount>();

@@ -253,7 +253,7 @@ unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {
 
     /// Convert the [`Arc`] into a raw pointer.
     ///
-    /// The raw pointer has ownership of the refcount that this Arc object owned.
+    /// The raw pointer has ownership of the refcount that this [`Arc`] object owned.
     pub fn into_raw(self) -> *const T {
         let ptr = self.ptr.as_ptr();
         core::mem::forget(self);

@@ -261,7 +261,7 @@ pub fn into_raw(self) -> *const T {
         unsafe { core::ptr::addr_of!((*ptr).data) }
     }
 
-    /// Return a raw pointer to the data in this arc.
+    /// Return a raw pointer to the data in this [`Arc`].
     pub fn as_ptr(this: &Self) -> *const T {
         let ptr = this.ptr.as_ptr();
 

@@ -305,7 +305,7 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
     /// Converts this [`Arc`] into a [`UniqueArc`], or destroys it if it is not unique.
     ///
-    /// When this destroys the `Arc`, it does so while properly avoiding races. This means that
+    /// When this destroys the [`Arc`], it does so while properly avoiding races. This means that
     /// this method will never call the destructor of the value.
     ///
     /// # Examples

@@ -345,11 +345,11 @@ pub fn into_unique_or_drop(this: Self) -> Option<Pin<UniqueArc<T>>> {
 
         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will
         // return without further touching the `Arc`. If the refcount reaches zero, then there are
-        // no other arcs, and we can create a `UniqueArc`.
+        // no other `Arc`s, and we can create a `UniqueArc`.
         if refcount.dec_and_test() {
             refcount.set(1);
 
-            // INVARIANT: We own the only refcount to this arc, so we may create a `UniqueArc`. We
+            // INVARIANT: We own the only refcount to this `Arc`, so we may create a `UniqueArc`. We
             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin
             // their values.
             Some(Pin::from(UniqueArc {

base-commit: dc59e4fea9d83f03bad6bddf3fa2e52491777482

Signature · 1 line
2.50.1 (Apple Git-155)
#1 lore raw
Quoted 11 lines · Harish-CS

The Arc documentation has a few mentions that do not follow the surrounding style: a plain Arc without an intra-doc link and a lower-case "arc".

Use intra-doc links for rustdoc references to Arc and spell internal comments consistently as Arc, matching nearby docs.

Suggested-by Miguel Ojeda <[email protected]>
Link https://github.com/Rust-for-Linux/linux/issues/1240
Signed-off-by Harish-CS <[email protected]>

Thanks for the patch! It looks good to me.

One question that I am supposed to ask: is Harish-CS a "known identity"?

https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

Normally, the full legal name is used (which may be what you wrote, in which case it is fine).

Cheers,
Miguel

reviewer
#2 lore raw
Quoted 7 lines · Miguel Ojeda

On Wed, Jul 8, 2026 at 7:51 PM Harish-CS <[email protected]> wrote:
Thanks for the patch! It looks good to me.

One question that I am supposed to ask: is Harish-CS a "known identity"?

Quoted 6 lines


https://docs.kernel.org/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

Normally, the full legal name is used (which may be what you wrote, in
which case it is fine).

JFYI: it also doesn't actually have to be your legal name, it just needs to be consistent and traceable to your online identity generally. Though if you are using your real name /and/ you have a last name it's probably better to use the full first/last name. Of course, if your language doesn't have last names generally - feel free to just let us know.

Quoted 3 lines

Cheers,
Miguel

#3 lore raw
Quoted 3 lines · On Tue, Jul 14, 2026 at 8:24 PM <[email protected]> wrote:

JFYI: it also doesn't actually have to be your legal name, it just needs to be consistent and traceable to your online identity generally.

Yeah, I didn't say it has to be, just that normally it is.

The reason is that if it is not the legal name, then it may not be as simple to accept the patch, especially lately for maintainers in some countries.

So for contributors that are OK confirming publicly that it is their legal name, it is the simplest approach :(

(For small patches it is not a big worry, but hopefully the contributor will end up contributing larger changes.)

Cheers,
Miguel

author
#4 lore raw

PATCH v2 1/1 rust: sync: improve `Arc` documentation links

In reply to Harish-CS

The Arc documentation has a few mentions that do not follow the surrounding style: a plain Arc without an intra-doc link and a lower-case "arc".

Use intra-doc links for rustdoc references to Arc and spell internal comments consistently as Arc, matching nearby docs.

Suggested-by Miguel Ojeda <[email protected]>
Link https://github.com/Rust-for-Linux/linux/issues/1240
Signed-off-by Harish C S <[email protected]>

---
Changes in v2:
- Use full name in the patch author and Signed-off-by trailer.

 rust/kernel/sync/arc.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
rust/kernel/sync/arc.rs +6 -6
index 5ac4961b7cd2..76a153e01283 100644
@@ -154,7 +154,7 @@ impl<T: ?Sized> ArcInner<T> {
     ///
     /// # Safety
     ///
-    /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the `Arc` must
+    /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the [`Arc`] must
     /// not yet have been destroyed.
     unsafe fn container_of(ptr: *const T) -> NonNull<ArcInner<T>> {
         let refcount_layout = Layout::new::<Refcount>();

@@ -253,7 +253,7 @@ unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {
 
     /// Convert the [`Arc`] into a raw pointer.
     ///
-    /// The raw pointer has ownership of the refcount that this Arc object owned.
+    /// The raw pointer has ownership of the refcount that this [`Arc`] object owned.
     pub fn into_raw(self) -> *const T {
         let ptr = self.ptr.as_ptr();
         core::mem::forget(self);

@@ -261,7 +261,7 @@ pub fn into_raw(self) -> *const T {
         unsafe { core::ptr::addr_of!((*ptr).data) }
     }
 
-    /// Return a raw pointer to the data in this arc.
+    /// Return a raw pointer to the data in this [`Arc`].
     pub fn as_ptr(this: &Self) -> *const T {
         let ptr = this.ptr.as_ptr();
 

@@ -305,7 +305,7 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
     /// Converts this [`Arc`] into a [`UniqueArc`], or destroys it if it is not unique.
     ///
-    /// When this destroys the `Arc`, it does so while properly avoiding races. This means that
+    /// When this destroys the [`Arc`], it does so while properly avoiding races. This means that
     /// this method will never call the destructor of the value.
     ///
     /// # Examples

@@ -345,11 +345,11 @@ pub fn into_unique_or_drop(this: Self) -> Option<Pin<UniqueArc<T>>> {
 
         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will
         // return without further touching the `Arc`. If the refcount reaches zero, then there are
-        // no other arcs, and we can create a `UniqueArc`.
+        // no other `Arc`s, and we can create a `UniqueArc`.
         if refcount.dec_and_test() {
             refcount.set(1);
 
-            // INVARIANT: We own the only refcount to this arc, so we may create a `UniqueArc`. We
+            // INVARIANT: We own the only refcount to this `Arc`, so we may create a `UniqueArc`. We
             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin
             // their values.
             Some(Pin::from(UniqueArc {
Signature · 1 line
2.50.1 (Apple Git-155)
maintainer Acked-by on v2 1/1
#5 lore raw
Quoted 10 lines · Harish C S

The Arc documentation has a few mentions that do not follow the surrounding style: a plain Arc without an intra-doc link and a lower-case "arc".

Use intra-doc links for rustdoc references to Arc and spell internal comments consistently as Arc, matching nearby docs.

Suggested-by Miguel Ojeda <[email protected]>
Link https://github.com/Rust-for-Linux/linux/issues/1240
Signed-off-by Harish C S <[email protected]>

Thanks!

Acked-by Boqun Feng <[email protected]>

Regards,
Boqun

Quoted 63 lines

---
Changes in v2:
- Use full name in the patch author and Signed-off-by trailer.

 rust/kernel/sync/arc.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
rust/kernel/sync/arc.rs +6 -6
index 5ac4961b7cd2..76a153e01283 100644
@@ -154,7 +154,7 @@ impl<T: ?Sized> ArcInner<T> {
     ///
     /// # Safety
     ///
-    /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the `Arc` must
+    /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the [`Arc`] must
     /// not yet have been destroyed.
     unsafe fn container_of(ptr: *const T) -> NonNull<ArcInner<T>> {
         let refcount_layout = Layout::new::<Refcount>();

@@ -253,7 +253,7 @@ unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {
 
     /// Convert the [`Arc`] into a raw pointer.
     ///
-    /// The raw pointer has ownership of the refcount that this Arc object owned.
+    /// The raw pointer has ownership of the refcount that this [`Arc`] object owned.
     pub fn into_raw(self) -> *const T {
         let ptr = self.ptr.as_ptr();
         core::mem::forget(self);

@@ -261,7 +261,7 @@ pub fn into_raw(self) -> *const T {
         unsafe { core::ptr::addr_of!((*ptr).data) }
     }
 
-    /// Return a raw pointer to the data in this arc.
+    /// Return a raw pointer to the data in this [`Arc`].
     pub fn as_ptr(this: &Self) -> *const T {
         let ptr = this.ptr.as_ptr();
 

@@ -305,7 +305,7 @@ pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 
     /// Converts this [`Arc`] into a [`UniqueArc`], or destroys it if it is not unique.
     ///
-    /// When this destroys the `Arc`, it does so while properly avoiding races. This means that
+    /// When this destroys the [`Arc`], it does so while properly avoiding races. This means that
     /// this method will never call the destructor of the value.
     ///
     /// # Examples

@@ -345,11 +345,11 @@ pub fn into_unique_or_drop(this: Self) -> Option<Pin<UniqueArc<T>>> {
 
         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will
         // return without further touching the `Arc`. If the refcount reaches zero, then there are
-        // no other arcs, and we can create a `UniqueArc`.
+        // no other `Arc`s, and we can create a `UniqueArc`.
         if refcount.dec_and_test() {
             refcount.set(1);
 
-            // INVARIANT: We own the only refcount to this arc, so we may create a `UniqueArc`. We
+            // INVARIANT: We own the only refcount to this `Arc`, so we may create a `UniqueArc`. We
             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin
             // their values.
             Some(Pin::from(UniqueArc {
Signature · 1 line
2.50.1 (Apple Git-155)
Applied
#6 lore raw
In reply to Harish C S
Quoted 11 lines · Harish C S

The Arc documentation has a few mentions that do not follow the surrounding style: a plain Arc without an intra-doc link and a lower-case "arc".

Use intra-doc links for rustdoc references to Arc and spell internal comments consistently as Arc, matching nearby docs.

Suggested-by Miguel Ojeda <[email protected]>
Link https://github.com/Rust-for-Linux/linux/issues/1240
Signed-off-by Harish C S <[email protected]>

Applied to rust-next -- thanks everyone!

Cheers,
Miguel