Add display of cfg in rustdoc

[GuillaumeGomez]

It's been a question since a while now. Should we display cfg flags or not? An example of the output:

If yes, should we display it like this or in another way?

cc @rust-lang/docs

[rust-highfive]

r? @QuietMisdreavus

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

[QuietMisdreavus]

I'm really skittish about just turning this on, because it could leave the impression that rustdoc can somehow handle conditional compilation, which it still totally does not. There's no way for rustdoc to show everything that's tagged with a feature, for the same reason it can't truly show everything that's tagged with a platform-specific cfg. (e.g. #43348 needed to specifically hand several modules to rustdoc via cfg(dox), and on top of that needed to add a new doc(cfg) attribute parameter to make sure rustdoc didn't try to execute doctests on it.)

This may be helpful if people remember to turn on all their features when rendering docs, but this leaves out things like docs.rs and even that #[cfg(not(feature = "foo"))] - since your example won't render that page in the first place if that feature is turned on! I think it could lead to some misleading docs; if people see that cfg tag in one place, they may think they can find all of them there.

[kennytm]

How will it looks like when applied to impl, functions, struct fields, enum variants, and fields inside enum variants?

#[cfg(foo)]
impl Foo {
    #[cfg(foo)]
    pub fn new() {}
}

#[cfg(foo)]
pub struct Foo {
    #[cfg(foo)]
    pub x: u32,
}

#[cfg(foo)]
pub enum Foo2 {
    #[cfg(foo)]
    Bar {
        #[cfg(foo)]
        baz: u32,
    }
}

[GuillaumeGomez]

That's the whole point of this debate. I want to propose this add because otherwise I'll have to update how gtk-rs docs are generated (yes, I'm a bit lazy).

[alexcrichton]

ping @rust-lang/doc, any thoughts on this PR?

[alexcrichton]

er, @rust-lang/docs

[steveklabnik]

I basically second @QuietMisdreavus ; I think this has the possibility of introducing more problems.

[GuillaumeGomez]

I think it's way too early as well. I'll close it then and we'll discuss about it later in the future.

[carols10cents]

Sounds like this should be closed, so I'm closing!