intra doc links towards parent crate succeed but create warnings

[rukai]

Problem

intra doc links towards parent crate succeed when generating docs for the parent crate but creates warnings like:

warning: `[Device]` cannot be resolved, ignoring it.
   --> /home/rukai2/Projects/Crates/wgpu/wgpu/wgpu-types/src/lib.rs:343:18
    |
343 | /// Describes a [`Device`].
    |                  ^^^^^^^^ cannot be resolved, ignoring
    |
    = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
    = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

But we can see here that it succeeds: https://wgpu.rs/doc/wgpu/struct.DeviceDescriptor.html

Steps

1. create a crate A
2. create a crate B that depends on A and reexports types from A (specify as local path dependency, issue does not occur with git)
3. a type in A contains intra doc links to types in B, which is then reexported by B. (only succeeds when reexported)
4. run cargo +nightly doc on crate B
5. This actually succeeds, which is great. Unfortunately it also creates warnings, that the type cannot be resolved.

Notes

Output of cargo version: cargo 1.46.0-nightly (089cbb80b 2020-06-15)

A workaround PR for this issue was made for wgpu gfx-rs/wgpu#748

This issue is kind of obscure, so I wouldnt be surprised if the best solution is for the user to just add an allow for the warning, but figured I would make an issue in case its useful.

[ehuss]

Transferred to the rust-lang/rust repository, where the rustdoc tool lives.

[jyn514]

create a crate B that depends on A and reexports types from A (specify as local path dependency, issue does not occur with git)
a type in A contains intra doc links to types in B, which is then reexported by B. (only succeeds when reexported)

This will break links as well once #73101 is merged. In general I don't think intra-doc links were designed for this use case, but you could try using absolute paths on the off chance it works.

[jyn514]

Note also that the link would be broken currently if you only documented A, it looks like it works because you always document the two crates at the same time.

[rukai]

Ok, yeah thats fine, if the links break in the future we'll just remove them I guess.

[cwfitzgerald]

Absolute links absolutely work going forward in the dep tree (I did it before realizing that intra-doc links worked). I understand that this is the proper thing to do, but it makes me sad as my docs in wgpu-types will get much more annoying in the future.

[jyn514]

Now that #73101 has been merged this should be closed as wontfix, you can't refer to upstream crates because they're not in scope. The links will now both create warnings and not generate the links you meant.

[jyn514]

I opened #74481 for the general issue of linking to upstream documentation.