rust: enable rustdoc's `--generate-link-to-definition`
Subsystems (2)
Miguel Ojeda
maintainerRFC 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
@@ -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
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:
-
Defaultpoints to the rendered "Traitcore::default::Default" page (not the source view, since it goes to another crate, though this may change).-
LockClassKeypoints to thepub struct LockClassKey(...);line in the same page, highlighting the line number.-
Self::new()points to thepub 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.
Cc Guillaume Gomez <[email protected]>Link https://elixir.bootlin.com [3]Link https://rust.docs.kernel.org [4]Signed-off-by Miguel Ojeda <[email protected]>
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@@ -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
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.
Reviewed-by Gary Guo <[email protected]>
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
Miguel Ojeda
AppliedQuoted 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:
-
Defaultpoints to the rendered "Traitcore::default::Default" page (not the source view, since it goes to another crate, though this may change).-
LockClassKeypoints to thepub struct LockClassKey(...);line in the same page, highlighting the line number.-
Self::new()points to thepub 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.
Cc Guillaume Gomez <[email protected]>Link https://elixir.bootlin.com [3]Link https://rust.docs.kernel.org [4]Signed-off-by Miguel Ojeda <[email protected]>
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
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:
-
Defaultpoints to the rendered "Traitcore::default::Default" page (not the source view, since it goes to another crate, though this may change).-
LockClassKeypoints to thepub struct LockClassKey(...);line in the same page, highlighting the line number.-
Self::new()points to thepub 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.
Cc Guillaume Gomez <[email protected]>Link https://elixir.bootlin.com [3]Link https://rust.docs.kernel.org [4]Signed-off-by Miguel Ojeda <[email protected]>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
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