PinDerefMutHelper should not show up in impl DerefMut for Pin

[Darksonn]

Location (URL)

https://doc.rust-lang.org/nightly/std/pin/struct.Pin.html#impl-DerefMut-for-Pin%3CPtr%3E

Summary

The PR #145608 explicitly contains measures using #[cfg(doc)] to ensure that the docs are rendered in a certain way. This works locally, as can be seen from the locally generated docs in #145608 (comment), but on doc.rust-lang.org this does not seem to apply.

Perhaps --cfg doc is not applied when building docs for the website, even though they are applied locally?

[fmease]

To clarify upfront, this happens to the std re-export of this impl (as linked in the issue description), not to the core definition.

rustdoc sets --cfg doc when documenting a crate. However, when it inlines cross-crate re-exports as it's the case for the std façade which fully reexports core (in which Pin and that impl is defined), it looks into the build artifacts (rmeta/rlib) of the dependencies which were produced by rustc ….

However, cargo doc (re)uses the artifacts produced by the build step ("cargo build") to avoid having to rebuild the entire dependency graph when documenting crates. This of course means that these artifacts weren't produced by rustc --cfg doc … but by rustc.

[fmease]

CC #114952, rust-lang/cargo#8811.

[fmease]

I don't remember if T-cargo has any plans to address rust-lang/cargo#8811 in the near future (i.e., not just documenting the crate graph with rustdoc but also (re)building the crate graph with rustc under --cfg doc when cargo doc is issued). It would indeed make cargo doc a lot more resource intensive.

Sadly, the only quickfix I can see would be to patch rustdoc to special case PinDerefMutHelper.

[Darksonn]

Oh, I see. We had a similar problem in Tokio where tokio-stream wants to show windows-only items on the unix docs, which requires not only tokio-stream but also tokio to be passed a special --cfg flag. In Tokio, we solved this issue like this:

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
# Issue #3770
#
# This should allow `docsrs` to be read across projects, so that `tokio-stream`
# can pick up stubbed types exported by `tokio`.
rustc-args = ["--cfg", "docsrs"]

I.e. we pass both rustdoc and rustc args when building docs to apply flags to dependencies too. Do we have a different --cfg flag that is applied to the entire crate graph when building docs?

[fmease]

I.e. we pass both rustdoc and rustc args when building docs to apply flags to dependencies too.

Yes, that's the way to manually solve this since Cargo doesn't do it by default.

Do we have a different --cfg flag that is applied to the entire crate graph when building docs?

I'm not sure if I understand the question correctly.

By default, no, there is no such cfg which is the crux of the issue; --cfg doc only gets set by rustdoc but not by rustc (nor passed to). Assuming a clean/full rebuild, with a crate graph of size N, rustdoc gets invoked N times and rustc gets invoked N-1 times when you execute cargo doc.

However, if by "we" and so on you're referring to the Rust Project and this repository (incl. all submodules+subtrees) and the artifacts that are produced by our build tool Bootstrap, then I guess we could modify src/bootstrap/ to pass --cfg doc to rustc (or to cargo doc via RUSTFLAGS; I don't know if it invokes Cargo or rustc/rustdoc) when ./x doc / ./x dist (doc) is issued.

[Darksonn]

Yes I just meant the Rust Project build.

Surely Rust already had to solve this problem? Rust displays target-specific features from all targets in the same doc build, and I don't see how Rust could do that without a way to pass --cfg doc or a different flag to dependencies. Otherwise, target-specific items in std would be unable to use target-specific items from core.