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

From: Miguel Ojeda
Date: Sun Aug 18 2024 - 10:13:09 EST


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@xxxxxxxxx>
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@xxxxxxxxxx>
---
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
--
2.46.0