[PATCH] rust: convert raw URLs to Markdown autolinks in comments

[PATCH] rust: convert raw URLs to Markdown autolinks in comments

[Xizhe Yin]

From: xizheyin <xizheyin@smail.nju.edu.cn>

Some comments in Rust files use raw URLs (http://example.com) rather
than Markdown autolinks [text](URL). This inconsistency makes the
documentation less uniform and harder to maintain.

This patch converts all remaining raw URLs in Rust code comments to use
the Markdown autolink format, maintaining consistency with the rest of
the codebase which already uses this style.

Link: Rust-for-Linux#1153
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: Xizhe Yin <xizheyin@smail.nju.edu.cn>
---
 rust/kernel/alloc.rs               | 2 +-
 rust/kernel/alloc/allocator.rs     | 2 +-
 rust/kernel/cred.rs                | 2 +-
 rust/kernel/kunit.rs               | 2 +-
 rust/kernel/miscdevice.rs          | 2 +-
 rust/kernel/print.rs               | 2 +-
 rust/kernel/rbtree.rs              | 2 +-
 rust/kernel/std_vendor.rs          | 4 ++--
 rust/kernel/sync/arc/std_vendor.rs | 4 ++--
 9 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/rust/kernel/alloc.rs b/rust/kernel/alloc.rs
index fc9c9c41cd79..d2f067ed8986 100644
--- a/rust/kernel/alloc.rs
+++ b/rust/kernel/alloc.rs
@@ -152,7 +152,7 @@ pub unsafe trait Allocator {
     /// - aligned to `layout.align()`,
     ///
     /// Additionally, `Flags` are honored as documented in
-    /// <https://docs.kernel.org/core-api/mm-api.html#mm-api-gfp-flags>.
+    /// [kernel documentation: GFP flags](https://docs.kernel.org/core-api/mm-api.html#mm-api-gfp-flags).
     fn alloc(layout: Layout, flags: Flags) -> Result<NonNull<[u8]>, AllocError> {
         // SAFETY: Passing `None` to `realloc` is valid by its safety requirements and asks for a
         // new memory allocation.
diff --git a/rust/kernel/alloc/allocator.rs b/rust/kernel/alloc/allocator.rs
index aa2dfa9dca4c..2e05ae842b62 100644
--- a/rust/kernel/alloc/allocator.rs
+++ b/rust/kernel/alloc/allocator.rs
@@ -6,7 +6,7 @@
 //! linked below. For instance, this includes the concept of "get free page" (GFP) flags and the
 //! typical application of the different kernel allocators.
 //!
-//! Reference: <https://docs.kernel.org/core-api/memory-allocation.html>
+//! Reference: [kernel documentation: Memory Allocation](https://docs.kernel.org/core-api/memory-allocation.html)
 
 use super::Flags;
 use core::alloc::Layout;
diff --git a/rust/kernel/cred.rs b/rust/kernel/cred.rs
index 2599f01e8b28..589557e18d79 100644
--- a/rust/kernel/cred.rs
+++ b/rust/kernel/cred.rs
@@ -6,7 +6,7 @@
 //!
 //! C header: [`include/linux/cred.h`](srctree/include/linux/cred.h).
 //!
-//! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html>
+//! Reference: [kernel documentation: Credentials](https://www.kernel.org/doc/html/latest/security/credentials.html)
 
 use crate::{
     bindings,
diff --git a/rust/kernel/kunit.rs b/rust/kernel/kunit.rs
index 1604fb6a5b1b..ec0d4889cc12 100644
--- a/rust/kernel/kunit.rs
+++ b/rust/kernel/kunit.rs
@@ -4,7 +4,7 @@
 //!
 //! C header: [`include/kunit/test.h`](srctree/include/kunit/test.h)
 //!
-//! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
+//! Reference: [kernel documentation: KUnit](https://docs.kernel.org/dev-tools/kunit/index.html)
 
 use core::{ffi::c_void, fmt};
 
diff --git a/rust/kernel/miscdevice.rs b/rust/kernel/miscdevice.rs
index fa9ecc42602a..3cbd0258475c 100644
--- a/rust/kernel/miscdevice.rs
+++ b/rust/kernel/miscdevice.rs
@@ -6,7 +6,7 @@
 //!
 //! C headers: [`include/linux/miscdevice.h`](srctree/include/linux/miscdevice.h).
 //!
-//! Reference: <https://www.kernel.org/doc/html/latest/driver-api/misc_devices.html>
+//! Reference: [kernel documentation: Miscdevices](https://www.kernel.org/doc/html/latest/driver-api/misc_devices.html)
 
 use crate::{
     bindings,
diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
index cf4714242e14..896a2ef2652a 100644
--- a/rust/kernel/print.rs
+++ b/rust/kernel/print.rs
@@ -4,7 +4,7 @@
 //!
 //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
 //!
-//! Reference: <https://docs.kernel.org/core-api/printk-basics.html>
+//! Reference: [kernel documentation: Printk basics](https://docs.kernel.org/core-api/printk-basics.html)
 
 use crate::{
     ffi::{c_char, c_void},
diff --git a/rust/kernel/rbtree.rs b/rust/kernel/rbtree.rs
index 5246b2c8a4ff..a9b10ae73dbf 100644
--- a/rust/kernel/rbtree.rs
+++ b/rust/kernel/rbtree.rs
@@ -4,7 +4,7 @@
 //!
 //! C header: [`include/linux/rbtree.h`](srctree/include/linux/rbtree.h)
 //!
-//! Reference: <https://docs.kernel.org/core-api/rbtree.html>
+//! Reference: [kernel documentation: Rbtree](https://docs.kernel.org/core-api/rbtree.html)
 
 use crate::{alloc::Flags, bindings, container_of, error::Result, prelude::*};
 use core::{
diff --git a/rust/kernel/std_vendor.rs b/rust/kernel/std_vendor.rs
index 279bd353687a..ae2a56d7cdc7 100644
--- a/rust/kernel/std_vendor.rs
+++ b/rust/kernel/std_vendor.rs
@@ -3,9 +3,9 @@
 //! Rust standard library vendored code.
 //!
 //! The contents of this file come from the Rust standard library, hosted in
-//! the <https://github.com/rust-lang/rust> repository, licensed under
+//! the [rust-lang/rust](https://github.com/rust-lang/rust) repository, licensed under
 //! "Apache-2.0 OR MIT" and adapted for kernel use. For copyright details,
-//! see <https://github.com/rust-lang/rust/blob/master/COPYRIGHT>.
+//! see [rust-lang/rust/blob/master/COPYRIGHT].
 
 /// [`std::dbg`], but using [`pr_info`] instead of [`eprintln`].
 ///
diff --git a/rust/kernel/sync/arc/std_vendor.rs b/rust/kernel/sync/arc/std_vendor.rs
index 11b3f4ecca5f..a95002ee4add 100644
--- a/rust/kernel/sync/arc/std_vendor.rs
+++ b/rust/kernel/sync/arc/std_vendor.rs
@@ -3,9 +3,9 @@
 //! Rust standard library vendored code.
 //!
 //! The contents of this file come from the Rust standard library, hosted in
-//! the <https://github.com/rust-lang/rust> repository, licensed under
+//! the [rust-lang/rust](https://github.com/rust-lang/rust) repository, licensed under
 //! "Apache-2.0 OR MIT" and adapted for kernel use. For copyright details,
-//! see <https://github.com/rust-lang/rust/blob/master/COPYRIGHT>.
+//! see [rust-lang/rust/blob/master/COPYRIGHT].
 
 use crate::sync::{arc::ArcInner, Arc};
 use core::any::Any;
-- 
2.49.0

Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

[Miguel Ojeda]

On Sun, Apr 6, 2025 at 5:51 AM Xizhe Yin <xizheyin@smail.nju.edu.cn> wrote:
>
> From: xizheyin <xizheyin@smail.nju.edu.cn>

This should ideally match your Signed-off-by.

> Some comments in Rust files use raw URLs (http://example.com) rather
> than Markdown autolinks [text](URL). This inconsistency makes the
> documentation less uniform and harder to maintain.
>
> This patch converts all remaining raw URLs in Rust code comments to use
> the Markdown autolink format, maintaining consistency with the rest of
> the codebase which already uses this style.
>
> Link: Rust-for-Linux#1153
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>

I am really a newbie on the Markdown spec, but as far as I can tell,
Markdown autolinks are the `<...>` ones:

    https://spec.commonmark.org/0.31.2/#autolinks

So what I was trying to suggest adding a few missing `<>` to a few raw
URLs we have.

By the way, the "Link" should be a full URL to the issue here :)

Thanks  for the patch!

Cheers,
Miguel

[PATCH] rust: convert raw URLs to Markdown autolinks in comments

[Xizhe Yin]

From: xizheyin <xizheyin@smail.nju.edu.cn>

Some comments in Rust files use raw URLs (http://example.com) rather
than Markdown autolinks [text](URL). This inconsistency makes the
documentation less uniform and harder to maintain.

This patch converts all remaining raw URLs in Rust code comments to use
the Markdown autolink format, maintaining consistency with the rest of
the codebase which already uses this style.

Link: https://github.com/Rust-for-Linux/linux/issues/1153
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: xizheyin <xizheyin@smail.nju.edu.cn>
---
 rust/kernel/alloc/kbox.rs               | 2 +-
 rust/kernel/block/mq/gen_disk.rs        | 2 +-
 rust/kernel/std_vendor.rs               | 2 +-
 rust/kernel/sync/arc.rs                 | 2 +-
 rust/pin-init/examples/pthread_mutex.rs | 2 +-
 rust/pin-init/src/lib.rs                | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/rust/kernel/alloc/kbox.rs b/rust/kernel/alloc/kbox.rs
index b77d32f3a58b..604d12c6f5bd 100644
--- a/rust/kernel/alloc/kbox.rs
+++ b/rust/kernel/alloc/kbox.rs
@@ -101,7 +101,7 @@
 pub type KVBox<T> = Box<T, super::allocator::KVmalloc>;
 
 // SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee:
-// https://doc.rust-lang.org/stable/std/option/index.html#representation).
+// <https://doc.rust-lang.org/stable/std/option/index.html#representation>).
 unsafe impl<T, A: Allocator> ZeroableOption for Box<T, A> {}
 
 // SAFETY: `Box` is `Send` if `T` is `Send` because the `Box` owns a `T`.
diff --git a/rust/kernel/block/mq/gen_disk.rs b/rust/kernel/block/mq/gen_disk.rs
index 14806e1997fd..cd54cd64ea88 100644
--- a/rust/kernel/block/mq/gen_disk.rs
+++ b/rust/kernel/block/mq/gen_disk.rs
@@ -129,7 +129,7 @@ pub fn build<T: Operations>(
             get_unique_id: None,
             // TODO: Set to THIS_MODULE. Waiting for const_refs_to_static feature to
             // be merged (unstable in rustc 1.78 which is staged for linux 6.10)
-            // https://github.com/rust-lang/rust/issues/119618
+            // <https://github.com/rust-lang/rust/issues/119618>
             owner: core::ptr::null_mut(),
             pr_ops: core::ptr::null_mut(),
             free_disk: None,
diff --git a/rust/kernel/std_vendor.rs b/rust/kernel/std_vendor.rs
index 279bd353687a..abbab5050cc5 100644
--- a/rust/kernel/std_vendor.rs
+++ b/rust/kernel/std_vendor.rs
@@ -148,7 +148,7 @@ macro_rules! dbg {
     };
     ($val:expr $(,)?) => {
         // Use of `match` here is intentional because it affects the lifetimes
-        // of temporaries - https://stackoverflow.com/a/48732525/1063961
+        // of temporaries - <https://stackoverflow.com/a/48732525/1063961>
         match $val {
             tmp => {
                 $crate::pr_info!("[{}:{}:{}] {} = {:#?}\n",
diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs
index 8484c814609a..350c380bb8d4 100644
--- a/rust/kernel/sync/arc.rs
+++ b/rust/kernel/sync/arc.rs
@@ -135,7 +135,7 @@ pub struct Arc<T: ?Sized> {
     // meaningful with respect to dropck - but this may change in the future so this is left here
     // out of an abundance of caution.
     //
-    // See https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking
+    // See <https://doc.rust-lang.org/nomicon/phantom-data.html#generic-parameters-and-drop-checking>
     // for more detail on the semantics of dropck in the presence of `PhantomData`.
     _p: PhantomData<ArcInner<T>>,
 }
diff --git a/rust/pin-init/examples/pthread_mutex.rs b/rust/pin-init/examples/pthread_mutex.rs
index 9164298c44c0..5ac22f1880d2 100644
--- a/rust/pin-init/examples/pthread_mutex.rs
+++ b/rust/pin-init/examples/pthread_mutex.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-// inspired by https://github.com/nbdd0121/pin-init/blob/trunk/examples/pthread_mutex.rs
+// inspired by <https://github.com/nbdd0121/pin-init/blob/trunk/examples/pthread_mutex.rs>
 #![allow(clippy::undocumented_unsafe_blocks)]
 #![cfg_attr(feature = "alloc", feature(allocator_api))]
 #[cfg(not(windows))]
diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs
index 05c44514765e..0806c689f693 100644
--- a/rust/pin-init/src/lib.rs
+++ b/rust/pin-init/src/lib.rs
@@ -1447,7 +1447,7 @@ macro_rules! impl_zeroable {
     {<T: ?Sized + Zeroable>} UnsafeCell<T>,
 
     // SAFETY: All zeros is equivalent to `None` (option layout optimization guarantee:
-    // https://doc.rust-lang.org/stable/std/option/index.html#representation).
+    // <https://doc.rust-lang.org/stable/std/option/index.html#representation>).
     Option<NonZeroU8>, Option<NonZeroU16>, Option<NonZeroU32>, Option<NonZeroU64>,
     Option<NonZeroU128>, Option<NonZeroUsize>,
     Option<NonZeroI8>, Option<NonZeroI16>, Option<NonZeroI32>, Option<NonZeroI64>,
-- 
2.49.0

Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

[Miguel Ojeda]

On Sun, Apr 6, 2025 at 1:13 PM 尹熙喆 <xizheyin@smail.nju.edu.cn> wrote:
>
> Thank you very much for the reminder, I will resend a new patch as requested.
> But it seems to me that this patch makes sense to a certain extent for the improvement of the raw links in the doc, which might make the document look better.
> Do you think it's necessary to keep it, or do you have a better suggestion? :)

(Please do not send HTML -- it will not reach the mailing list)

You're welcome!

Personally, I think it depends on the URL and the context -- let me
give clarify below.

The `[...](...)` notation is "heavier", i.e. makes it harder to read
in plain-text form, which many people use in the kernel, i.e. they
will not read the rendered form. That is why we typically move the
links below and just use `[...]` instead if we really want to use a
"title" rather than the raw URL.

Moreover, if a raw URL already says what it is itself, then there is
less reason to use a title. So, for instance, a URL like:

    https://rust-for-linux.com/contributing

already says everything it needs to say. However, a URL that uses e.g.
opaque IDs into a database may not give you any information until you
click on them.

So, for both reasons, I think the following is not an improvement, in
both plain-text and rendered forms:

    -//! Reference: <https://docs.kernel.org/core-api/rbtree.html>
    +//! Reference: [kernel documentation:
Rbtree](https://docs.kernel.org/core-api/rbtree.html)

By the way, the last changes, i.e.

    -//! see <https://github.com/rust-lang/rust/blob/master/COPYRIGHT>.
    +//! see [rust-lang/rust/blob/master/COPYRIGHT].

wouldn't work anyway, or am I missing something? (Even if it did, we
should avoid changing vendored files, by the way).

Cheers,
Miguel

Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

[Miguel Ojeda]

On Sun, Apr 6, 2025 at 1:28 PM Xizhe Yin <xizheyin@smail.nju.edu.cn> wrote:
>
> than Markdown autolinks [text](URL). This inconsistency makes the

The commit message here needs an update. But, yeah, the contents look
like what I meant, thanks! :)

I think there is another in rust/kernel/block/mq/gen_disk.rs and one
in scripts/generate_rust_target.rs.

Also, the changes in `*_vendor.rs` files should probably be skipped,
since we try to keep those as close to upstream as possible.

Please Cc also others that may maintain particular files, e.g. Benno
for pin-init (you can use `scripts/get_maintainer.pl`):

    https://rust-for-linux.com/contributing#submitting-changes-to-existing-code
    https://rust-for-linux.com/contributing#submitting-patches

Finally, please increment the version number of the patch series when
sending a new version (e.g. `git format-patch -v3`).

Thanks!

Cheers,
Miguel

Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

[尹熙喆]

Thank you for the detailed explanation, I completely understand it.
I just sent a new patch which uses autolink in comments. if you have time you can review it.

Best wishes
xizhe

Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

[尹熙喆]

I submitted the v3 version of the patch, sorry for the trouble. After this submission, I am familiar with some of the process, but I believe I need to spend more time reading through the documentation.

By the way, where can I see the latest emails? I'm interested in this project and would like to keep up to date with the latest progress.

Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

[Miguel Ojeda]

On Sun, Apr 6, 2025 at 2:27 PM 尹熙喆 <xizheyin@smail.nju.edu.cn> wrote:
>
> I submitted the v3 version of the patch, sorry for the trouble. After this submission, I am familiar with some of the process, but I believe I need to spend more time reading through the documentation.

Thanks, and no need to apologize!

> By the way, where can I see the latest emails? I'm interested in this project and would like to keep up to date with the latest progress.

Please see https://lore.kernel.org/rust-for-linux/

Cheers,
Miguel