Tracking issue for #[doc(cfg(…))], #[doc(cfg_hide(…))] and doc_auto_cfg

[kennytm]

This is a tracking issue for the #[doc(cfg(…))] attribute (feature: doc_cfg) introduced in #43348 and #[doc(cfg_hide(…))] (feature: doc_cfg_hide) attribute introduced in #89596, along with the doc_auto_cfg feature introduced in #90502.

Steps:

• Implement: Expose all OS-specific modules in libstd doc. #43348
• Fix syntax mismatches: Rustdoc and rustc accept different cfg syntax #84437 (fixed in Unify rustc and rustdoc parsing of cfg() #84442)
• Adjust documentation (see instructions on forge) (Update documentation for doc_cfg feature #92818)
• RFC (RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features rfcs#3631)
• Update implementation to match RFC (Implement RFC 3631: add rustdoc doc_cfg features #138907)
• Check performance impact on big crates
• Update documentation to match RFC
• Stabilization PR (see instructions on forge):

(cc #1998)

[sfackler]

#[cfg(rustdoc)] is also gated on this issue but seems distinct (and less risky). Could we FCP that portion in particular?

[asomers]

I think that #[cfg(rustdoc)], when applied to structs, should automatically skip any non-public members. That would greatly reduce the amount of extra typing required by crates like Nix.

[Nemo157]

I was just trying this out for documenting crate features, it "works" but if this is a potential usecase it would be nice to special case the rendering for it:

---

---

[Nemo157]

There is also the issue that it repeats every feature on every item in a page:

When I last attempted to do something about rendering features I found it much more useful to separately keep track of "all required features" to render at the top of the items page and "newly introduced features" to render on the sub-items on the page, so you don't get this distracting repetition on every item.

[dtolnay]

We tried out this feature in Syn (dtolnay/syn#734) and decided against using it yet.

What I am happy with

I like how the message turns out at the top of the doc page of a single type or function.

We had previously displayed this information using an italicized note, which was less noticeable.

What I am not happy with

Our index page becomes extremely noisy. I wish there were a way to not show all of these in our case. It is enough to have this information on the type's individual page. Cfg combinations are not among the most important information to show on the index page.

Also inheriting the same note onto every public field seems unnecessary in our use case.

[joshka]

I noticed today that feature flags on derived traits don't get annotated and there's no obvious way to add an annotation

e.g.:

#![feature(doc_auto_cfg)]
#![feature(doc_cfg)]

use std::fmt;

// this doesn't display the feature flag
#[cfg_attr(unix, derive(Debug))]
pub struct Foo;

// this works
#[cfg(unix)]
// #[doc(cfg(unix))] // if not using auto_cfg
impl fmt::Display for Foo {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Foo")
    }
}

rendered with cargo-docs-rs:

Is there a way that this should be able to work, or is it a known missing part of this? If the latter, I'd note that it's likely not a blocking one IMO, but a nice to have.

[jhpratt]

I'm not sure how that even could work theoretically, given that #[cfg_attr] is evaluated first.

[joshka]

Perhaps something like the following?:

#[cfg_attr(unix, derive(Debug))]
#[doc(cfg_impl(unix, Debug))]
struct Foo;

What is it about the code generated by the compiler derive attribute that makes it not able to be annotated the same way a manual impl might be?

[est31]

As another method to what @joshka said, one could introduce a #[doc(cfg_attr(...))] attribute and make cfg_attr expand to it in addition to #[derive(Debug)]. It would be ignored by rustdoc, as making sense of it should be job of the derive macros: one would need to add support to all the derive macros to recognize that #[doc(cfg_attr(...))] attribute and transform it to a #[doc(cfg(...))] on the impl block.

The advantage would be that it's automatic compared to cfg_impl, but it would need derive authors to opt into this.

If you don't do such a transformation, like in @joshka 's proposal, rustdoc would need some way to find the right impl block (thanks to generics there can be multiple). Eg it could put the note on all impl blocks that come from expansions (Span::from_expansion).

There is also the whole question of what to do in the case the cfg evaluates to false and the derive macro does not run. You can't just create a fake impl Debug for Foo, as you need to get the generic params right: it could just as well be a impl<T: Debug + SomeTraitFromFooTypeDecl> for Foo<T>. Probably the impl block would just not be shown in that case.

[jhpratt]

I thought about this some more...it may be possible if the attribute is stored along with an annotation as to how it was enabled (if not by nature of not needing to be). This is already done to an extent as far as I'm aware, as diagnostics knows about cfged out items.

[joshka]

To be clear, my cfg_impl proposal was not a fully formed / thought out one. It was very off the cuff and I expect there's likely many downsides to be explored before jumping on that idea. My knowledge of the implementation necessary for this is fairly limited.

[GuillaumeGomez]

It's supposed to work. It's a known issue: #103300

The problem is rustc doesn't provide information when expanding items under cfg_attr. The best way here would be to add the corresponding cfg attribute on each generated item.

[jhpratt]

For those only subscribed to the tracking issue, the RFC is currently in FCP: rust-lang/rfcs#3631 (comment)

[Manishearth]

@GuillaumeGomez I've updated the list in the issue since it misleadingly shows that the feature is implemented/documented when the RFC changed things.

[GuillaumeGomez]

Good idea! Also linked the implementation PR in the first comment (#138907).