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@gmail.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@kernel.org>
---
 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

On Sun, Aug 18, 2024 at 4:13 PM Miguel Ojeda <ojeda@kernel.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@gmail.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@kernel.org>

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!


Le dim. 25 août 2024 à 22:22, Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> a écrit :
>
> On Sun, Aug 18, 2024 at 4:13 PM Miguel Ojeda <ojeda@kernel.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@gmail.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@kernel.org>
>
> 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

On Sun, Aug 25, 2024 at 10:25 PM Guillaume Gomez
<guillaume1.gomez@gmail.com> wrote:
>
> 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

On Sun, 18 Aug 2024 16:12:49 +0200
Miguel Ojeda <ojeda@kernel.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@gmail.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@kernel.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@garyguo.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

On Sun, Aug 18, 2024 at 8:19 PM Gary Guo <gary@garyguo.net> wrote:
>
> 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@garyguo.net>

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