Add an intra-doc link disambiguator for fields

[camelid]

I have code like this:

struct Foo { bar: i32 }

impl Foo {
    /// Get a reference to [`Foo::bar`].
    //                            ^^^ I want this to link to the field. Currently it links to the method.
    fn bar(&self) -> i32 { self.bar }
}

This is a decently-common Rust "design pattern" where you have have a private field but give public read-only access via a method of the same name. However, there's no way in rustdoc currently to disambiguate between the function and the field. Rustdoc seems to always link to the method in this case.

It would be good if we had a disambiguator for struct/enum fields: something like field@Foo::bar. I don't think it's necessary to have a different one for struct vs enum variant fields, but we should still decide that since intra-doc links are now stable (and thus we can't remove things).

See the discussion on Zulip.

cc @jyn514

[camelid]

It would be nice if we had special-casing for the disambiguator so that [`field@Foo::bar`] renders as Foo.bar. That would save a lot of doing [`Foo.bar`][field@Foo::bar].

[GoldsteinE]

IMHO using [`Foo.bar`] to create a link to the field is much more intuitive than [`Foo.bar`][field@Foo::bar] and generally looks nicer. Fields can’t even be referred with ::, so it’s hard to guess this syntax.

[JarredAllen]

IMHO using [`Foo.bar`] to create a link to the field is much more intuitive than [`Foo.bar`][field@Foo::bar] and generally looks nicer. Fields can’t even be referred with ::, so it’s hard to guess this syntax.

Yeah, I second this. [`Foo::bar`] for unambiguous cases needs to stick around for backwards-compatibility, but I think [`Foo.bar`] is a better disambiguator for fields than [`field@Foo::bar`]. It matches the syntax used to access it better, and also imo it fits cleaner into the pattern of [`Foo::bar()`] and [`Foo::bar!`] disambiguators for methods and macros.

[GoldsteinE]

I think I’m willing to contribute this if the idea itself gets accepted. I kinda don’t have the energy to push it, ping relevant people, write justifications and do other social stuff like that right now. I’m not even sure how to make (organisational) progress here, since this issue exists for 3 years and there’s no reaction from the rustdoc team.

[jyn514]

You are talking about a different problem than the one mentioned in the issue. We are not planning to add . to the intra doc link syntax for the reasons mentioned in https://github.com/rust-lang/rust/issues/75437.

[GoldsteinE]

That’s kinda sad but fair. How about special-casing [`field@Foo::bar`] to render as Foo.bar that @camelid wrote about?

[jyn514]

That should probably have an FCP from the rustdoc team. You can bring it up on Zulip if you want to get initial feedback on whether they think it's a good idea: https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc

[gondolyr]

For anyone that is still looking for a way to link to a struct field, adding #structfield.<FIELDNAME> at the end of the link seems to work as a workaround, where <FIELDNAME> is the struct field you wish to link to (without the angle brackets).

This appears to generate the following URL when I generate the docs with rustdoc: file:///home/myuser/my_project/target/doc/my_sub_module/struct.Foo.html#structfield.bar

Example:

struct Foo {
    bar: i32,
}

impl Foo {
    // THE LINE BELOW ⬇️
    /// Get a reference to [`crate::my_sub_module::Foo#structfield.bar`].
    fn bar(&self) -> i32 {
        self.bar
    }
}