cfg(doc) is not respected on cross-crate re-export

[notriddle]

I tried this code:

// crate a
pub struct MyStruct;
#[cfg(doc)]
impl MyStruct {
    pub fn doc_only_method() {}
}

// crate b
#[doc(inline)]
pub use a::MyStruct;

I expected to see this happen: I expected doc_only_method to appear in crate b

Instead, this happened: It didn't.

Meta

This issue can be reproduced in both the stable and nightly version of the compiler.

[GuillaumeGomez]

I think it's because the deps are not built with this cfg, only when rustdoc is run on them do we have them.

[fmease]

Yes, exactly.

This is essentially a Cargo issue. If you were to manually use rustc and rustdoc to document your projects, you could just pass --cfg doc to each rustc invocation to avoid this issue entirely.

If I understand cargo doc correctly, for a project with N crates, it calls rustc N-1 times (to produce .rmeta files for cross-crate reexports) and rustdoc N times¹ assuming a clean target directory. Now, we could in theory update cargo doc to pass --cfg doc to each rustc invocation. However that would force Cargo to recompile every single dependency whereas presently it can just reuse .rmeta files produced in a previous cargo <check|build|run> run which greatly reduces the time it takes to document your project.

Correct me if I'm wrong. cargo doc --verbose tells you the rustc and rustdoc invocations.

Footnotes

1. For cargo doc --no-deps, I think it's rustc N-1 times, rustdoc 1 time ↩

[Fryuni]

I think cargo doc doesn't set this config at all, it is injected by rustdoc in the generate_config function if I'm not mistaken. I'd post a link but copy link is not working correctly on my phone.

I though rustdoc was responsible for recursing through the dependencies, but if it gets information from executions of rust then this should be added to cargo doc

[fmease]

You might be right about generate_config, although that shouldn't contradict anything I was saying. Cargo doesn't pass --cfg doc to rustc which is the problem. The .rmeta files used by cross-crate reexports represent crates that weren't compiled with --cfg doc while ideally they would but that would require recompilation (cfgs have changed) drastically worsening the build times of docs in incremental settings.

Disclaimer: This is just what I can remember, I haven't double-checked any of this.

[fmease]

I though rustdoc was responsible for recursing through the dependencies

No, neither rustc nor rustdoc do that, that's the task of Cargo (or of any other Rust package manager).

[Fryuni]

Should we open an issue about this on cargo then? (Or someone did that already? If yes could share the link here pls)

I opened an issue there: rust-lang/cargo#12533

I found a few possibly related issues, but not specific for this:

• Pass --cfg doc to check builds of dependencies as part of cargo doc/rustdoc cargo#8811
• Cargo doc does not pass --cfg doc for build scripts cargo#8944
• #[cfg(doc)] does not work in Cargo.toml cargo#11570

Since the doc config is currently added by rustdoc itself it seems this is not handled by cargo at all.