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.

[clarfonthey]

Just poking around: it appears that the doc_auto_cfg feature links here, but there's no docs in the unstable book for it and the feature doesn't seem to match what's proposed in the RFC. Is this just not implemented, or is the syntax different and this just isn't documented?

[GuillaumeGomez]

The RFC (which is still under discussion so maybe not its final form) proposes something slightly different than what's currently implemented and adds more attributes to give more control.

Currently, to enable this feature, you use #![doc(auto_cfg)] and that's it.

[jmillikin]

Two years ago on #100883 I asked about the possibility of stabilizing #[doc(cfg(...)) without #[doc(auto_cfg)] on the principle that the former seems to be well-understood, while the latter is a more complex feature that has ongoing discussion about how exactly it should work.

At the time, the response was that stabilizing #[doc(cfg(...))] by itself wouldn't provide a good user experience, and that there would potentially be ecosystem churn from people adding it all over and then removing it once #[doc(auto_cfg)] was ready.

But ... it's been two years, and neither is stabilized. I could have been using #[doc(cfg(...)] all this time. It's pretty frustrating to have a ready-to-stabilize feature I want be blocked on a vaguely-related feature that I don't particularly care about.

Can #[doc(cfg(...))] please be stabilized? Feel free to put some verbiage in the release notes like "if you're planning to use #[doc(auto_cfg)] in the future then please hold on until that arrives" if there's still a concern about ecosystem churn.

[jhpratt]

@jmillikin This needs an RFC to be stabilized. That's currently awaiting FCP (it needs 3 more checkboxes): rust-lang/rfcs#3631 (comment)

[jmillikin]

I understand why #[doc(auto_cfg)] needs an RFC.

Why would #[doc(cfg(...))] need an RFC?

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