Support for showing explicit enum discriminant values in rustdoc

[Enselic]

Currently, enum discriminant values are not included in the HTML output. The code

pub enum E {
    V = 42,
}

renders like this:

However, it is easy to imagine a public API where the discriminant value matters. For example, some lib code could look like this:

#[repr(u8)]
pub enum Key {
    A = 65, // the value is the ASCII code for 'A'
}

and client code like this:

let key = std::io::stdin().bytes().next().unwrap().unwrap();
if key == Key::A as u8 {
    println!("A was typed")
}

In this example, the enum discriminant value is part of the public API of the library, so it would make sense to somehow make rustdoc include enum discriminant values in the rendered HTML.

Depending on the context, it is however perfectly reasonable to consider enum discriminant values to be an implementation detail, even explicit enum discriminant values. So it should also be supported to make sure they are NOT displayed.

The exact mechanism for this is still to be decided. See Zulip for some discussion on this. But most likely rustdoc should never show the enum discriminant value if they are not explicitly defined.

@rustbot label T-rustdoc

[jsha]

One of the most common situations where the enum discriminants should be documented is when using IntoPrimitive/TryFromPrimitive, as mentioned in the example from cargo-public-api/cargo-public-api#121.

#[derive(num_enum::IntoPrimitive, num_enum::TryFromPrimitive)]
#[repr(u32)]

One way to achieve the desired effect for this subset of primitives would be to add to the TryFromPrimitive derive macro so that it adds a #[doc()] attribute to each enum variant that documents its value. The values would then show up under the Variants section as documentation. This would be a great way to experiment with documenting enum values without needing new attributes from rustdoc.