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)
• Stabilization PR (see instructions on forge): Stabilize doc_cfg feature #79263

(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.

[jhpratt]

It's a new, non-trivial language feature. They don't get added on a whim; there's a process to follow.

[clarfonthey]

While it feels like one feature may be easier to stabilise, I can't imagine that filing a shorter RFC just for doc(cfg(...)) will go any faster. Plus, once the RFC for both features is added, I think it would be reasonable to stabilise just that feature since it doesn't really need any more work done.

So, I get the impatience, just, this is pretty much all volunteer work, so, it's gonna take a while for folks to set aside the time to review everything and sign off on it.

[theemathas]

For reference, writing the following at the top of lib.rs will make feature-gated stuff documented properly on docs.rs, while still having your program compiling in stable rust:

#![cfg_attr(docsrs, feature(doc_auto_cfg))]

[jmillikin]

#[cfg_attr(docsrs), ...] doesn't help for people who are trying to run rustdoc as part of their build and/or CI process, so it would be nice to get support for at least #[doc(cfg(...))] stabilized.

[GuillaumeGomez]

It's all or nothing. RFC is open and waiting for reviews. Sadly there is nothing more we can do about it.

The cfg_attr trick also works with features. Nothing prevents you do to run your CI in nightly. It's not the best but until the RFC is merged and the feature implemented (this part should be pretty quick), nothing else can be done.

[jmillikin]

I'm sorry, this may be a really dumb question, but why is it "all or nothing"?

I don't understand why #[doc(cfg(...))] can't be stabilized as an MVP, independent of #[doc(auto_cfg)]. They're both already implemented, and from the perspective of writing a stabilization report and/or updating the reference the former feature seems a lot easier to document (since it's entirely explicit annotations by the author).

[jhpratt]

Theoretically it could be done separately, but it wouldn't be done any faster (which seems to be what you truly want). There is nothing that can be done to speed up stabilization (at least that's within the code of conduct).

[jmillikin]

Theoretically it could be done separately, but it wouldn't be done any faster (which seems to be what you truly want). There is nothing that can be done to speed up stabilization (at least that's within the code of conduct).

I've frequently seen subsets of a complex feature stabilize separately, most famously the various parts of async stabilizing as the design was iterated on. I've also seen existing RFCs get split up into an MVP and a follow-on with more complexity but better ergonomics.

It could be that there's some aspect of how #[doc(cfg(...))] and #[doc(auto_cfg)] interact that I'm missing due to lack of rustc internals knowledge, but from an outside perspective it's not obvious why #[doc(cfg(....))] couldn't be split off and stabilized by itself (e.g. in 1.85 or 1.86), and then #[doc(auto_cfg))] can stabilize on its own timeframe (presumably >= 1.90).

[jhpratt]

Note that when features are split up it's generally because there are concerns, unresolved questions, or simply too much work to do all at once. None of that applies here. The only blocker (pending concerns being raised) is checkboxes.

[GuillaumeGomez]

In addition to what @jhpratt said: because it would need to go through an RFC, which means asking people to write another RFC and yet other people to review it. We have limited bandwidth and most contributors are not paid to do so and we're also facing a huge burn-out issue across the project as well so it wouldn't help in this regard either.

[madsmtm]

I've pinged the people that the FCP is waiting for (no flak intended towards any of these wonderful people), hopefully that can speed up the progress a little bit.

[GuillaumeGomez]

1. Please don't.
2. Likely not.

[madsmtm]

Apologies then.

[SpriteOvO]

#[cfg_attr(docsrs), ...] doesn't help for people who are trying to run rustdoc as part of their build and/or CI process

@jmillikin This is the solution I have been using.

Cargo.toml

[package.metadata.docs.rs]
all-features = true

[build-dependencies]
rustc_version = "0.4.1"

build.rs

use rustc_version::{version_meta, Channel};

fn main() {
    // Set cfg flags depending on release channel
    let channel = match version_meta().unwrap().channel {
        Channel::Stable => "CHANNEL_STABLE",
        Channel::Beta => "CHANNEL_BETA",
        Channel::Nightly => "CHANNEL_NIGHTLY",
        Channel::Dev => "CHANNEL_DEV",
    };
    println!("cargo:rustc-cfg={}", channel)
}

lib.rs

#![cfg_attr(all(doc, CHANNEL_NIGHTLY), feature(doc_auto_cfg))]

Then run nightly in your CI script, doc_auto_cfg will only be enabled when using nightly toolchain. So this works very well with CI and docs.rs and doesn't affect library users.

[fjarri]

The way I have it set up:

Cargo.toml:

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

lib.rs:

#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]

CI (mimicking docs.rs settings), with the nightly toolchain:

env RUSTDOCFLAGS='--cfg docsrs -D warnings' cargo doc --all-features

@jmillikin, does that not solve your problem?

[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.