Rust: Tracking issue for `#[doc(cfg(...))]`

[kennytm]

This is a tracking issue for the #[doc(cfg(...))] attribute introduced in #43348.

Steps:

• [x] Implement
• [ ] Adjust documentation (see instructions on forge)
• [ ] 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 (https://github.com/dtolnay/syn/pull/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.

[Lokathor]

The links in the opening post have gone dead.

[jhpratt]

What's the status of this? I've been using it on the time crate for as long as I can remember, and a number of other crates have been doing so as well.

[Nemo157]

For searchability: this is feature doc_cfg.

[Nemo157]

I changed the rendering of feature="foo" cfgs in #75330, which vastly simplifies the display on module index pages like shown in the syn screenshot above. I have also just opened #77672 to address the other point @dtolnay had, that there is no need to repeat the exact same cfg rendering over and over when it is already implied by context.

Other than those changes, there are bugs around trait implementation handling such as #68100, I want to try and create an exhaustive test covering trait implementations once #77672 is done and fix their handling.

After that, I feel like this would be ready for stabilization, it's had quite thorough usage on docs.rs already, so when rendering is all fixed we can rebuild the documentation for some large crates like tokio that use it and check whether there's other edgecase bugs remaining.

[ArniDagur]

I'm wondering: Would it not make sense to generate doc_cfg hints automatically for any #[cfg(...)] items, without also needing to type #[doc(cfg(...))]?

So the following

#[cfg(all(target_feature = "avx", target_feature = "avx2"))]
#[doc(cfg(all(target_feature = "avx", target_feature = "avx2")))]
pub mod avx;

could just be

#[cfg(all(target_feature = "avx", target_feature = "avx2"))]
pub mod avx;

Otherwise, we're duplicating information unnecessarily, right?

[Lokathor]

...pretty much

[Nemo157]

In the general case yes, but there are quite a few crates using things like internal cfg's generated by their build.rs for compiler version detection that would not want to show those cfg to their users.

[jyn514]

What about the opposite - having #[doc(cfg(x))] also imply #[cfg(x)]? I can't imagine a scenario where you wouldn't want to have that.

[jyn514]

Not sure how hard that would be to implement, though - maybe @petrochenkov would know?