rustdoc: skip // some variants omitted if enum is #[non_exhaustive]

[Ezrashaw]

Fixes #108925

Never touched rustdoc before so probably not the best code.

cc @dtolnay

[rustbot]

r? @jsha

(rustbot has picked a reviewer for you, use r? to override)

[rustbot]

Some changes occurred in src/librustdoc/clean/types.rs

cc @camelid

[Ezrashaw]

@jsha I've added the lint and implemented your advice in the linked issue.

As per the linked issue, Enum1 warns with the new lint. Enum2 and Enum3 have identical output, just the #[non_exhaustive] attribute.

@rustbot ready

[camelid]

I think this lint may need a crater run to make sure the warning doesn't cause too much breakage. I'm also not familiar with the motivation for this change, but in some ways, I think the lint may be a better fit for clippy. The reason is I'm a bit concerned it could be triggered by valid code.

[Ezrashaw]

@camelid I'm not convinced by this change now, it breaks libcore which obviously has -D warnings. While it's impossible to merge this PR, I do think that libcore and co have bad code in this regard. For example, take this snippet from libbacktrace:

/// The styles of printing that we can print
#[derive(Copy, Clone, Eq, PartialEq)]
pub enum PrintFmt {
    /// Prints a terser backtrace which ideally only contains relevant information
    Short,
    /// Prints a backtrace that contains all possible information
    Full,
    #[doc(hidden)]
    __Nonexhaustive,
}

It's just wrong and the exact thing this lint is for.

Not sure where you want to go from here.

[camelid]

@Ezrashaw Thanks for looking into the breakage! I do think this lint could potentially be a good fit for clippy (though they'd have to be consulted of course).

I'd also like to hear what @jsha's thoughts are on this since he proposed the lint: Do you think moving it to clippy would make sense?

[jsha]

I have to admit I don't know the factors that would favor a rustdoc lint or a clippy lint. Above you mention that it could be triggered by valid code. Are rustdoc lints only for input that is definitely invalid?

[Ezrashaw]

@jsha Not sure if someone else was going to answer this; nobody else has so here goes: I think that possibly valid code should never be triggered by (warn-by-default) rustdoc lints, period. I think that the question here is really: is code valid if it contains #[doc(hidden)] variants whilst not being #[non_exhaustive]. I am of the opinion that such code is invalid, but libcore contains code which triggers the lint (+ -D warnings so we can't compile the standard library).

The bottom line is: there is nothing we can feasibly do while this lint exists to get it to pass CI. I'll remove the lint and maybe we can land the one-line change which is the other part of this PR..

[notriddle]

I think this lint makes more sense in Clippy than in Rustdoc.

[Ezrashaw]

@notriddle Agreed, I've removed that part of the PR, now there is just the one liner fix which the linked issue was primarily concerned with.

[Ezrashaw]

@jsha Can we land this now?

[camelid]

I updated the title since I believe the content of this PR has changed.

[GuillaumeGomez]

Please add a test for it and then I'll approve it. Also, if not done already, I think adding this as a clippy lint would be nice. Please at least open an issue there so it's not forgotten.

[notriddle]

@bors r=notriddle,GuillaumeGomez rollup

[bors]

📌 Commit e0ec9c0 has been approved by notriddle,GuillaumeGomez

It is now in the queue for this repository.

[bors]

🌲 The tree is currently closed for pull requests below priority 100. This pull request will be tested once the tree is reopened.