False warnings with cargo doc.

[prataprc]

First raised this issue with rust-random/rand rust-random/rand#737. But the documentation links seem to work fine. So may be it is false-warning raised by cargo doc ?

How to reproduce ?

$ git clone git@github.com:bnclabs/llrb-index.git
$ cd llrb-index

$ rustup which cargo
<path>/toolchains/nightly-x86_64-unknown-linux-gnu/bin/cargo

$ cargo doc

[GuillaumeGomez]

I'll take a look.

[QuietMisdreavus]

I took a closer look at this yesterday and today, and found some of the warnings that were in fact spurious - the ones that corresponded to a link that was actually resolved on the item's page. I've opened #58972 to fix those.

However, there were some left that were not spurious in the same way. These all tripped a warning because the links can resolve in the original location in the original crate, but not the re-exported location in the facade crate. (The links are resolved all over again each time the item re-exports into a full page - the information isn't saved across crates, so as a hack we use the location of the re-export to resolve links.) Once #58972 is merged, the remaining warnings will need more effort to fix.

EDIT: I'd meant to give an example of an actual resolution failure - in the RngCore trait docs, it links to an impls module, which is present in the rand_core crate where RngCore is declared, but is not present in the rand crate where it's re-exported. This causes the link to fail to render, causing an erroneous [impls] to appear in the rendered documentation.

Another example is the TimerError enum, re-exported from the rand_jitter crate. It links back to a method its original JitterRng struct via the intra-doc link crate::JitterRng::test_timer, which is the correct path in rand_jitter, but not in rand - where the full path is crate::rngs::JitterRng::test_timer.

[dhardy]

Thanks for looking into this.

The latter issues sound tricky to solve — correct documentation for an item presented differently in two different places. I wonder if doc attributes could be made optional depending on which crate the item is being exported from? Ideally here we'd just want a different path for test_timer but significantly different docs for RngCore.

[GuillaumeGomez]

@QuietMisdreavus and I handled the issue differently: I don't show errors on items that are outside of the current crate and they prevent to read non-local items (so no errors since it's not parsed).