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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <CANiq72=c7yzLM4C-zctYFpUnFbQ2o4i5Uhp73xc4Td3-H_yDeQ@mail.gmail.com>
Date: Sun, 6 Apr 2025 13:42:38 +0200
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: 尹熙喆 <xizheyin@...il.nju.edu.cn>
Cc: rust-for-linux <rust-for-linux@...r.kernel.org>, 
	linux-kernel <linux-kernel@...r.kernel.org>, Miguel Ojeda <ojeda@...nel.org>
Subject: Re: [PATCH] rust: convert raw URLs to Markdown autolinks in comments

On Sun, Apr 6, 2025 at 1:13 PM 尹熙喆 <xizheyin@...il.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