linux-kernel - Re: [RFC PATCH] rust: enable rustdoc's `--generate-link-to-definition`

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 for Android: free password hash cracker in your pocket

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

Message-ID: <20240818191938.20ee1766.gary@garyguo.net>
Date: Sun, 18 Aug 2024 19:19:38 +0100
From: Gary Guo <gary@...yguo.net>
To: Miguel Ojeda <ojeda@...nel.org>
Cc: Alex Gaynor <alex.gaynor@...il.com>, Wedson Almeida Filho
 <wedsonaf@...il.com>, Jonathan Corbet <corbet@....net>, Boqun Feng
 <boqun.feng@...il.com>, Björn Roy Baron
 <bjorn3_gh@...tonmail.com>, Benno Lossin <benno.lossin@...ton.me>, Andreas
 Hindborg <a.hindborg@...sung.com>, Alice Ryhl <aliceryhl@...gle.com>,
 rust-for-linux@...r.kernel.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, patches@...ts.linux.dev, Konstantin Ryabitsev
 <konstantin@...uxfoundation.org>, Guillaume Gomez
 <guillaume1.gomez@...il.com>
Subject: Re: [RFC PATCH] rust: enable rustdoc's
 `--generate-link-to-definition`

On Sun, 18 Aug 2024 16:12:49 +0200
Miguel Ojeda <ojeda@...nel.org> wrote:

> In Rust 1.56.0 [1], rustdoc introduced the "jump to definition"
> feature [2], i.e. the unstable flag `--generate-link-to-definition`.
> It adds links to the source view of the documentation.
> 
> For instance, in the source view of `rust/kernel/sync.rs`, for this code:
> 
>     impl Default for LockClassKey {
>         fn default() -> Self {
>             Self::new()
>         }
>     }
> 
> It will add three hyperlinks:
> 
>   - `Default` points to the rendered "Trait `core::default::Default`"
>     page (not the source view, since it goes to another crate, though
>     this may change).
> 
>   - `LockClassKey` points to the `pub struct LockClassKey(...);` line
>     in the same page, highlighting the line number.
> 
>   - `Self::new()` points to the `pub const fn new() -> Self { ... }`
>     associated function, highlighting its line numbers (i.e. for the
>     full function).
> 
> This makes the source view more useful and a bit closer to the experience
> in e.g. the Elixir Cross Referencer [3].
> 
> I have provisionally enabled it for rust.docs.kernel.org [4] -- one can
> take a look at the source view there for an example of how it looks like.
> 
> Thus enable it.
> 
> Cc: Guillaume Gomez <guillaume1.gomez@...il.com>
> Link: https://github.com/rust-lang/rust/pull/84176 [1]
> Link: https://github.com/rust-lang/rust/issues/89095 [2]
> Link: https://elixir.bootlin.com [3]
> Link: https://rust.docs.kernel.org [4]
> Signed-off-by: Miguel Ojeda <ojeda@...nel.org>

Hi Miguel,

Thanks for doing this! When I visited rust.docs.kernel.org yesterday I
noticed that the definition links already existed, and it was very
useful.

Reviewed-by: Gary Guo <gary@...yguo.net>

Best,
Gary


> ---
>  rust/Makefile | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/rust/Makefile b/rust/Makefile
> index 1f10f92737f2..d311bcc30226 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -63,6 +63,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
>  	OBJTREE=$(abspath $(objtree)) \
>  	$(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
>  		$(rustc_target_flags) -L$(objtree)/$(obj) \
> +		-Zunstable-options --generate-link-to-definition \
>  		--output $(rustdoc_output) \
>  		--crate-name $(subst rustdoc-,,$@) \
>  		$(if $(rustdoc_host),,--sysroot=/dev/null) \
> 
> base-commit: 7c626ce4bae1ac14f60076d00eafe71af30450ba