rustdoc regression: inter-crate links not being generated where they previously were

[tarcieri]

We recently received multiple reports in the @RustCrypto project of missing links in the docs.rs documentation, and did manage to find a somewhat minimal illustration of the problem/

We previously had documentation which linked to types in the generic-array crate: https://docs.rs/digest/0.10.1/digest/type.Output.html

At some point those links broke. Here is where I first observed it: https://docs.rs/digest/0.10.2/digest/type.Output.html

Not sure how to properly file this issue, especially as I often experience these links not working on local rustdoc builds but being present on docs.rs. I can at least confirm I reproduced how the v0.10.2+ docs.rs builds appear via a local rustdoc build.

[JustAnotherCodemonkey]

I see that this needs a mcve. The provided example seems relatively minimal. What would constitute a mcve and how would one go about testing this without playing around with an actual crate on docs.rs?

[fmease]

I see that this needs a mcve. The provided example seems relatively minimal. What would constitute a mcve […]?

@JustAnotherCodemonkey, while the example is a nice reproducer, it's far from minimal: The incorrectly documented item Output is defined in a 2K SLoC crate, digest, which has several (transitive) dependencies amounting to 165KB in size. Most notably it depends on typenum which has 6K SLoC. An MCVE only consists of a single (if the bug can be reproduced with a single crate) or two files (if the bug is a cross-crate re-export bug & thus needs two crates) containing only a few items like 1 – 12 (each).
That's why I tagged this with E-needs-mcve Call for participation: This issue has a repro, but needs a Minimal Complete and Verifiable Example .

Note that @GuillaumeGomez wrote here that they would look into a very similar (if not a duplicate of this) issue. They may or may not try to the find a reproducer themself now. An MCVE isn't always necessary to find the root cause but it's still necessary to be able to add a regression test.

Sometimes someone very familiar with the code base may already have a hunch what went wrong even without an MCVE or they may remember a recent PR that touched relevant parts of the code base or they may bisect a commit range to search for a regressing commit.

[…] how would one go about testing this without playing around with an actual crate on docs.rs?

Well typically you download or git-clone (with a depth of 1) the relevant crate and try to minimize it which is a bit of an art form or trial-and-error. Check out http://blog.pnkfx.org/blog/2019/11/18/rust-bug-minimization-patterns/ for example (note that -Z unpretty=everybody_loops used in the article no longer exists). There are also several minimization tools: E.g., https://github.com/Nilstrieb/cargo-minimize, https://github.com/langston-barrett/treereduce. And then you basically start out with cargo doc and possibly end with invoking rustdoc directly.

_{Crate stats were taken from https://lib.rs/.}

[tarcieri]

@fmease I'd agree the problem looks related to typenum: we're experiencing similar problems with crates using hybrid-array, a generic-array alternative, which would seem to rule out generic-array itself.

[GuillaumeGomez]

The problem shows up with cargo rustdoc and with cargo doc --deps. Since it doesn't have other crates information, it doesn't generate links to their items. Normally, -Zrustdoc-map should allow to go around this limitation, checking why it's not the case.

[GuillaumeGomez]

I opened rust-lang/cargo#13481, it should fix this issue.

[tarcieri]

It looks like that PR is merged. Can I expect the changes to be live on docs.rs then?

[GuillaumeGomez]

If the new cargo nightly has been released, you should be able to.

[newpavlov]

I think this issue can be closed? We probably should ask the docs.rs team to re-generate docs, but I wonder if it can be done automatically (i.e. all dependencies of generic-array published in the affected date range), since it will be hard to create a full list manually.

[GuillaumeGomez]

Indeed! Closing then.