Consider omitting "some variants omitted" in enum documentation if enum is non_exhaustive

[dtolnay]

code	rustdoc
pub enum Enum1 { A, B, #[doc(hidden)] C, }
#[non_exhaustive] pub enum Enum2 { A, B, }
#[non_exhaustive] pub enum Enum3 { A, B, #[doc(hidden)] C, }

Would it be reasonable for Rustdoc to produce exactly the same output for Enum2 and Enum3? I think so. These two types have an identical public API.

Separately, would it be reasonable for Rustdoc to produce exactly the same output for Enum1 and Enum2? Whether that means printing a synthetic #[non_exhaustive] attribute on Enum1 instead of the // some variants omitted comment, or some other approach that unifies all three of these outputs.

Meta

rustc --version --verbose:

rustc 1.70.0-nightly (e3dfeeaa4 2023-03-07)
binary: rustc
commit-hash: e3dfeeaa45f117281b19773d67f3f253de65cee1
commit-date: 2023-03-07
host: x86_64-unknown-linux-gnu
release: 1.70.0-nightly
LLVM version: 15.0.7

[Ezrashaw]

IMHO, #[non_exhaustive] for both is more clear. It better conveys meaning.

I'm happy to work on this but I've never touched rustdoc before so I might need some help.
@rustbot claim

EDIT: is it acceptable to literally .push() a new attribute onto it.attrs?

[jsha]

I think it's important that the docs not disagree with behavior users can observe from the compiler. So we shouldn't document a #[non_exhaustive] attribute when none exists because a user could write an exhaustive match and not get a compile error (even though they might have had to look at the source to do so).

I think it would be reasonable for Enum2 and Enum3 to render as Enum2 is today:

For Enum1, I think there should be a doc lint warning if there is a doc(hidden) variant without the enum being marked #[non_exhaustive].

[Ezrashaw]

@jsha I agree, a doc lint sounds like the best idea because semantically Enum1 is #[non_exhaustive] even if not technically so.

I see that you are the reviewer on the linked PR, I've marked it as a draft for now and will re-implement with your suggestion. I assume that @dtolnay broadly agrees from the OP?