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

[Miguel Ojeda]

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