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)
• 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.

[jyn514]

As a reminder, this is a tracking issue for stabilizing doc_cfg. Bug reports should go in separate issues to avoid pinging the 30+ people watching this issue, unless you think the bug is so severe it should block stabilization. Suggestions for enhancements should also go in separate issues.

---

As far as I can tell, the current status is that the stabilization PR (#100883) is blocked on deciding whether doc_auto_cfg should be on by default or not (and whether we should let crate authors control whether it's on or just force it on). The discussion for that is in https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Discussion.20about.20.60doc_cfg*.60.20features.20stabilization/.

[GuillaumeGomez]

Thanks for the sum up. We actually decided to go through an RFC that started to be written because too many elements need to be discussed. More information in the next weeks.

[joseluis]

Since I see an RFC is being written, I take the opportunity to share my case, since I wanted to use doc_cfg to show that a particular function is only available on the absence of a feature. But it seems that's not currently possible.

This does result in: "Available on feature safe only".

#[cfg(feature = "safe")]
#[doc(cfg(feature = "safe"))]
pub fn safe_fn() {}

But this results in: "Available on non-crate feature safe only". Instead of the expected: "Not available on feature safe".

#[cfg(not(feature = "safe"))]
#[doc(cfg(not(feature = "safe")))]
pub fn unsafe_fn() {}

I wonder if this is by design.

[Nemo157]

I wonder if this is by design.

Somewhat, yes. Cargo itself doesn't support negative features, so no effort was put into making them render well.

[nic-hartley]

Should the original post link to #100883 instead?

[seancroach]

I'm running into a rather annoying problem with documenting features.

I am writing currently a serde crate with multiple specifications for a specific format. I have a binary module that is documented with the following doc_cfg: any(feature = "be", feature = "le", feature = "varint"). Now, if I document one of the functions as present with just the be feature and inline their re-export I get this annoying display:

Of course, I tried with doc_cfg_hide, wrestling with the minimal documentation, but nothing seems to work for this. I can not inline the re-exports, but purposefully sacrificing usability is presumably a bug or at least something worth mentioning here. When I don't inline it, it looks like so:

My one gripe with the first selection is that even the order it's appended to is non-uniform, which bothers me, but that's not the core issue here.

Is there some hack I'm unaware of besides not inlining items in documentation? I haven't seen this case discussed so far. Even if I simplified it to an internal feature (binary) it still displays, even if assumed to be enabled in context; either way, extraneous information is applied, and I have no say in omitting it.

[GuillaumeGomez]

#[doc(no_inline)]

[seancroach]

I believe #[doc(no_inline)] (as described here) is specifically the behavior I'm trying to avoid. As you can see, binary is a public module.

I understand this is stylistic, but every serde_* crate uses #[doc(inline)] on their re-exported functions. This is the behavior I want.

The behavior I don't want is my inability to omit the automatically appended features. It introduces a ton of noise. Even if I make some "internal" feature named binary, it still adds itself (non-uniformly in terms of order) to the re-exported functions. I've made this an issue here because it seems like not too rare of a use-case that makes documenting features so noisy that it becomes unhelpful at-a-glance.

In summary, I can either not inline my re-exports, or deal with unhelpful documented features; it seems like a bug that I can't simply do both, even if it means manually overriding the item at its declaration to say exactly what I want to document.

[Nemo157]

It should certainly be possible to simplify be and std and (be or le or varint) to be and std, IIRC there are already some simplifications applied to the cfgs so this would just require extending those. It'd be good to open a separate issue with a small testcase.

[est31]

@Nemo157 see #104991

[GuillaumeGomez]

We'll need #103300 to be fixed beforehand as well.