rustdoc: Confusing intra-doc handling of `Self` in enum

[camelid]

This code works fine:

pub enum Foo {
    /// [Self::Bar::abc]
    Bar {
        abc: i32,
        xyz: i32,
    },
}

But this code's intra-doc link doesn't resolve:

pub enum Foo {
    Bar {
        abc: i32,
        /// [Self::Bar::abc]
        xyz: i32,
    },
}

warning: unresolved link to `Bar::Bar::abc`
 --> foo.rs:4:14
  |
4 |         /// [Self::Bar::abc]
  |              ^^^^^^^^^^^^^^ no item named `Bar` in scope
  |
  = note: `#[warn(broken_intra_doc_links)]` on by default

Doesn't Self usually only refer to types, not enum variants? (Barring the proposed RFC to make enum variant types.)

[camelid]

Yeah, this definitely seems like a bug. I have to use Foo::Self::abc (or Foo::Bar::abc). Self::abc doesn't work because it looks for the enum variant as if it's a free-floating type:

warning: unresolved link to `Bar::abc`
 --> foo.rs:4:14
  |
4 |         /// [Self::abc]
  |              ^^^^^^^^^ no item named `Bar` in scope
  |
  = note: `#[warn(broken_intra_doc_links)]` on by default

[jyn514]

@camelid do you know if this ever worked? I might have broken it in #76467.

[jyn514]

But also I agree that this seems like a misfeature, I'd be ok with getting rid of it. To do that, just delete variant_field and all references to it.

[hellow554]

hey @jyn514

you are correct. Bisecting this leads to b7ebc6b

So the fix is to get rid of the variant_field method completly (and of course delete any code that calls it)? Or am I misreading it?

[jyn514]

Yes, I think so. No one noticed this breaking for 12 weeks and Self always refers to the type in normal code, not the variant: https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=9655fe188d99f728e90e65a08164e825

[lucas-deangelis]

Hi, I don't know if anyone is already planning to work on it, but if not, would it be a good first issue? I'm still new to the language but I'd like to start contributing.

[camelid]

Yes, this should be a good first issue. You can claim it with @rustbot claim. Post here or on Zulip in #t-compiler/help if you have any questions :)

[lucas-deangelis]

Thanks! I'll have a look at it. @rustbot claim

[lucas-deangelis]

I've taken a deeper look at the issue, and at the doc on contributions to Rust. Correct me if I'm wrong, but I think I'm supposed to start with making a failing test case. I made a issue-82209.rs file in src/test/rustdoc/. Here's the file:

#![deny(broken_intra_doc_links)]
pub enum Foo {
    Bar {
        abc: i32,
        /// [Self::Bar::abc]
        xyz: i32,
    },
}

I'm not sure about the #![deny(broken_intra_doc_links)], but I couldn't get the test to fail without something like that, and it's more precise than the #![deny(warnings)] that I used at first. Does this look okay to you?