False warnings with cargo doc.

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

I'll take a look.

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.

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.

@QuietMisdreavus

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

Rollup merge of rust-lang#58972 - QuietMisdreavus:intra-doc-link-impo…

Auto merge of #58972 - QuietMisdreavus:intra-doc-link-imports, r=Guil…

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.

This sounds like it will be fixed by #73101, but I haven't tested on these exact crates.

I documented rand without warnings on the latest nightly, and the upstream issue has been closed (rust-random/rand#737), so I'm going to close this as well. Feel free to re-open if you still have issues!

Navigation Menu

Repository navigation

False warnings with cargo doc. #58745

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

False warnings with cargo doc. #58745

Description

Activity

GuillaumeGomez commented on Mar 3, 2019

QuietMisdreavus commented on Mar 6, 2019

dhardy commented on Mar 7, 2019

GuillaumeGomez commented on Mar 7, 2019

jyn514 commented on Jul 6, 2020

jyn514 commented on Aug 19, 2020

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions