Skip to contentSkip to conversation

rust: enable rustdoc's `--generate-link-to-definition`

RFC PATCH Applied Miguel Ojeda 4 participants 6 messages Aug 18, 2024 – Aug 25, 2024

Subsystems (2)
lore
Share & tools
lore

Miguel Ojeda

author maintainer
#0 lore raw

RFC PATCH 1/1 rust: enable rustdoc's `--generate-link-to-definition`

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.

---
 rust/Makefile | 1 +
 1 file changed, 1 insertion(+)
rust/Makefile +1 -0
index 1f10f92737f2..d311bcc30226 100644
@@ -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

Signature · 1 line
2.46.0
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 31 lines · On Sun, 18 Aug 2024 16:12:49 +0200 Miguel Ojeda <[email protected]> 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.

Quoted 8 lines

Thus enable it.

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.

Best,
Gary

Quoted 18 lines
---
 rust/Makefile | 1 +
 1 file changed, 1 insertion(+)
rust/Makefile +1 -0
index 1f10f92737f2..d311bcc30226 100644
@@ -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 lore raw
Quoted 6 lines · Gary Guo

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.

Thanks Gary, I appreciate that. Yeah, you caught me, I enabled it a week or two ago. I am very glad you already found it useful :)

Cheers,
Miguel

Applied
#3 lore raw
In reply to Miguel Ojeda
Quoted 32 lines · Miguel Ojeda

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.

Quoted 8 lines

Thus enable it.

Applied to rust-next -- thanks!

Let's enable this since it has already been useful for people. If it happens to break, we can always disable it. And it may help getting it stabilized.

Cheers,
Miguel

#4 lore raw

Don't hesitate if you encounter any bug to tell me so I can fix them.

Any feedback is also very appreciated!

Quoted 51 lines · Miguel Ojeda
Quoted 32 lines · Miguel Ojeda

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.

Quoted 8 lines

Thus enable it.

Applied to rust-next -- thanks!

Let's enable this since it has already been useful for people. If it happens to break, we can always disable it. And it may help getting it stabilized.

Cheers,
Miguel

#5 lore raw
Quoted 4 lines · Guillaume Gomez

Don't hesitate if you encounter any bug to tell me so I can fix them.

Any feedback is also very appreciated!

Thanks Guillaume, that is very appreciated!

We will hopefully not have to tell you about any bugs :)

Cheers,
Miguel