Intra-doc links are unresolved on `pub use _ as _` items #76073

Veetaha · 2020-08-29T18:15:52Z

I tried this code:

/// [`std::fs`]
pub use foo as foo2;

pub fn foo(){}

fn main() {}

I expected to see this happen:
If I run cargo +nightly doc I get no warnings/errors.

Instead, this happened:

$ cargo +nightly doc
 Documenting foo v0.1.0 (/home/veetaha/junk/rust-sandbox)
warning: unresolved link to `std::fs`
 --> src/main.rs:1:6
  |
1 | /// [`std::fs`]
  |      ^^^^^^^^^ unresolved link
  |
  = note: `#[warn(broken_intra_doc_links)]` on by default
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: 1 warning emitted

Note that if I remove pub from the use statement, no warnings are emitted...

Meta

rustc --version --verbose:

rustc 1.47.0-nightly (2d8a3b918 2020-08-26)
binary: rustc
commit-hash: 2d8a3b9181f41d3af9b9f016c5d73b2553e344bf
commit-date: 2020-08-26
host: x86_64-unknown-linux-gnu
release: 1.47.0-nightly
LLVM version: 11.0

rustdoc --version --verbose:

rustdoc 1.47.0-nightly (2d8a3b918 2020-08-26)
binary: rustdoc
commit-hash: 2d8a3b9181f41d3af9b9f016c5d73b2553e344bf
commit-date: 2020-08-26
host: x86_64-unknown-linux-gnu
release: 1.47.0-nightly
LLVM version: 11.0

The text was updated successfully, but these errors were encountered:

jyn514 · 2020-08-29T20:04:13Z

$ RUSTDOC_LOG=rustdoc::passes::collect=debug rustdoc +stage1 pub-use.rs 
2020-08-29T20:03:27.412092Z DEBUG rustdoc::passes::collect_intra_doc_links: attempting to resolve item without parent module: std::fs
warning: unresolved link to `std::fs`
 --> pub-use.rs:1:6
  |
1 | /// [`std::fs`]
  |      ^^^^^^^^^ unresolved link

This is a bug in rustdoc, it should resolve relative to the current module.

jyn514 · 2020-08-29T20:09:34Z

This will break #75756 until fixed.

jyn514 · 2020-08-29T20:12:18Z

For some reason tcx.parent() returns None on pub use items 🤔

jyn514 · 2020-08-29T20:31:44Z

Hmm, even after that's fixed it doesn't display the documentation anywhere ... @Veetaha did you expect it to show up above the re-export?

Or on the index page for the module?

Veetaha · 2020-08-29T20:35:20Z

Well, I would expect it to appear at least somewhere :D
Might it be an oversight in rust or rustdoc design that it is allowed to write doc comments on items where these doc comments are not rendered?
At the very least (even if unrendered) I would expect validation of the intra-doc link happening...

jyn514 · 2020-08-29T20:38:44Z

Right, #76082 fixes the incorrect error. If you don't have a preference I might put it on the pub use, although I wonder if maybe rustdoc should just give an error instead that you tried to put docs on a re-export.

Veetaha · 2020-08-29T20:42:09Z

Reexports are part of the crate's public API. I think it is reasonable to apply docs to them and have them rendered. We may collect more opinions on that before further decisions

@GuillaumeGomez

…uillaumeGomez Fix intra-doc links on pub re-exports Partial fix for rust-lang#76073 - This removes the incorrect error, but doesn't show the documentation anywhere. r? @GuillaumeGomez

@GuillaumeGomez

…uillaumeGomez Fix intra-doc links on pub re-exports Partial fix for rust-lang#76073 - This removes the incorrect error, but doesn't show the documentation anywhere. r? @GuillaumeGomez

@GuillaumeGomez

…uillaumeGomez Fix intra-doc links on pub re-exports Partial fix for rust-lang#76073 - This removes the incorrect error, but doesn't show the documentation anywhere. r? @GuillaumeGomez

@GuillaumeGomez

…uillaumeGomez Fix intra-doc links on pub re-exports Partial fix for rust-lang#76073 - This removes the incorrect error, but doesn't show the documentation anywhere. r? @GuillaumeGomez

jyn514 · 2020-09-08T05:01:05Z

Going to close this since the intra-doc issue is fixed - if you think rustdoc should show documentation on pub re-exports of items within your crate, that's a separate issue (but feel free to open a new issue for it!)

@estebank

…tebank Improve suggestions for broken intra-doc links ~~Depends on rust-lang#74489 and should not be merged before that PR.~~ Merged 🎉 ~~Depends on rust-lang#75916 and should not be merged before.~~ Merged Fixes rust-lang#75305. This does a lot of different things 😆. - Add `PerNS::into_iter()` so I didn't have to keep rewriting hacks around it. Also add `PerNS::iter()` for consistency. Let me know if this should be `impl IntoIterator` instead. - Make `ResolutionFailure` an enum instead of a unit variant. This was most of the changes: everywhere that said `ErrorKind::ResolutionFailure` now has to say _why_ the link failed to resolve. - Store the resolution in case of an anchor failure. Previously this was implemented as variants on `AnchorFailure` which was prone to typos and had inconsistent output compared to the rest of the diagnostics. - Turn some `Err`ors into unwrap() or panic()s, because they're rustdoc bugs and not user error. These have comments as to why they're bugs (in particular this would have caught rust-lang#76073 as a bug a while ago). - If an item is not in scope at all, say the first segment in the path that failed to resolve - If an item exists but not in the current namespaces, say that and suggests linking to that namespace. - If there is a partial resolution for an item (part of the segments resolved, but not all of them), say the partial resolution and why the following segment didn't resolve. - Add the `DefId` of associated items to `kind_side_channel` so it can be used for diagnostics (tl;dr of the hack: the rest of rustdoc expects the id of the item, but for diagnostics we need the associated item). - No longer suggests escaping the brackets for every link that failed to resolve; this was pretty obnoxious. Now it only suggests `\[ \]` if no segment resolved and there is no `::` in the link. - Add `Suggestion`, which says _what_ to prefix the link with, not just 'prefix with the item kind'. Places where this is currently buggy: <details><summary>All outdated</summary> ~~1. When the link has the wrong namespace:~~ Now fixed. <details> ```rust /// [type@S::h] impl S { pub fn h() {} } /// [type@T::g] pub trait T { fn g() {} } ``` ``` error: unresolved link to `T::g` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:53:6 | 53 | /// [type@T::g] | ^^^^^^^^^ | = note: this link partially resolves to the trait `T`, = note: `T` has no field, variant, or associated item named `g` error: unresolved link to `S::h` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:48:6 | 48 | /// [type@S::h] | ^^^^^^^^^ | = note: this link partially resolves to the struct `S`, = note: `S` has no field, variant, or associated item named `h` ``` Instead it should suggest changing the disambiguator, the way it currently does for macros: ``` error: unresolved link to `S` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:38:6 | 38 | /// [S!] | ^^ help: to link to the unit struct, use its disambiguator: `value@S` | = note: this link resolves to the unit struct `S`, which is not in the macro namespace ``` </details> 2. ~~Associated items for values. It says that the value isn't in scope; instead it should say that values can't have associated items.~~ Fixed. <details> ``` error: unresolved link to `f::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:14:6 | 14 | /// [f::A] | ^^^^ | = note: no item named `f` is in scope = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` ``` This is _mostly_ fixed, it now says ```rust warning: unresolved link to `f::A` --> /home/joshua/test-rustdoc/f.rs:1:6 | 1 | /// [f::A] | ^^^^ | = note: this link partially resolves to the function `f` = note: `f` is a function, not a module ``` 'function, not a module' seems awfully terse when what I actually mean is '`::` isn't allowed here', though. </details> It looks a lot nicer now, it says ``` error: unresolved link to `f::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:13:6 | 13 | /// [f::A] | ^^^^ | = note: `f` is a function, not a module or type, and cannot have associated items ``` 3. ~~I'm also not very happy with the second note for this error:~~ <details> ``` error: unresolved link to `S::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:19:6 | 19 | /// [S::A] | ^^^^ | = note: this link partially resolves to the struct `S`, = note: `S` has no field, variant, or associated item named `A` ``` but I'm not sure how better to word it. I ended up going with 'no `A` in `S`' to match `rustc_resolve` but that seems terse as well. </details> This now says ``` error: unresolved link to `S::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:17:6 | 17 | /// [S::A] | ^^^^ | = note: the struct `S` has no field or associated item named `A` ``` which I think looks pretty good :) 4. This is minor, but it would be nice to say that `path` wasn't found instead of the full thing: ``` error: unresolved link to `path::to::nonexistent::module` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:8:6 | 8 | /// [path::to::nonexistent::module] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` It will now look at most 3 paths up (so it reports `path::to` as not in scope), but it doesn't work with arbitrarily many paths. </details> ~~I recommend only reviewing the last few commits - the first 7 are all from rust-lang#74489.~~ Rebased so that only the relevant commits are shown. Let me know if I should squash the history some more. r? @estebank

…bank Improve suggestions for broken intra-doc links ~~Depends on rust-lang#74489 and should not be merged before that PR.~~ Merged 🎉 ~~Depends on rust-lang#75916 and should not be merged before.~~ Merged Fixes rust-lang#75305. This does a lot of different things 😆. - Add `PerNS::into_iter()` so I didn't have to keep rewriting hacks around it. Also add `PerNS::iter()` for consistency. Let me know if this should be `impl IntoIterator` instead. - Make `ResolutionFailure` an enum instead of a unit variant. This was most of the changes: everywhere that said `ErrorKind::ResolutionFailure` now has to say _why_ the link failed to resolve. - Store the resolution in case of an anchor failure. Previously this was implemented as variants on `AnchorFailure` which was prone to typos and had inconsistent output compared to the rest of the diagnostics. - Turn some `Err`ors into unwrap() or panic()s, because they're rustdoc bugs and not user error. These have comments as to why they're bugs (in particular this would have caught rust-lang#76073 as a bug a while ago). - If an item is not in scope at all, say the first segment in the path that failed to resolve - If an item exists but not in the current namespaces, say that and suggests linking to that namespace. - If there is a partial resolution for an item (part of the segments resolved, but not all of them), say the partial resolution and why the following segment didn't resolve. - Add the `DefId` of associated items to `kind_side_channel` so it can be used for diagnostics (tl;dr of the hack: the rest of rustdoc expects the id of the item, but for diagnostics we need the associated item). - No longer suggests escaping the brackets for every link that failed to resolve; this was pretty obnoxious. Now it only suggests `\[ \]` if no segment resolved and there is no `::` in the link. - Add `Suggestion`, which says _what_ to prefix the link with, not just 'prefix with the item kind'. Places where this is currently buggy: <details><summary>All outdated</summary> ~~1. When the link has the wrong namespace:~~ Now fixed. <details> ```rust /// [type@S::h] impl S { pub fn h() {} } /// [type@T::g] pub trait T { fn g() {} } ``` ``` error: unresolved link to `T::g` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:53:6 | 53 | /// [type@T::g] | ^^^^^^^^^ | = note: this link partially resolves to the trait `T`, = note: `T` has no field, variant, or associated item named `g` error: unresolved link to `S::h` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:48:6 | 48 | /// [type@S::h] | ^^^^^^^^^ | = note: this link partially resolves to the struct `S`, = note: `S` has no field, variant, or associated item named `h` ``` Instead it should suggest changing the disambiguator, the way it currently does for macros: ``` error: unresolved link to `S` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:38:6 | 38 | /// [S!] | ^^ help: to link to the unit struct, use its disambiguator: `value@S` | = note: this link resolves to the unit struct `S`, which is not in the macro namespace ``` </details> 2. ~~Associated items for values. It says that the value isn't in scope; instead it should say that values can't have associated items.~~ Fixed. <details> ``` error: unresolved link to `f::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:14:6 | 14 | /// [f::A] | ^^^^ | = note: no item named `f` is in scope = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` ``` This is _mostly_ fixed, it now says ```rust warning: unresolved link to `f::A` --> /home/joshua/test-rustdoc/f.rs:1:6 | 1 | /// [f::A] | ^^^^ | = note: this link partially resolves to the function `f` = note: `f` is a function, not a module ``` 'function, not a module' seems awfully terse when what I actually mean is '`::` isn't allowed here', though. </details> It looks a lot nicer now, it says ``` error: unresolved link to `f::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:13:6 | 13 | /// [f::A] | ^^^^ | = note: `f` is a function, not a module or type, and cannot have associated items ``` 3. ~~I'm also not very happy with the second note for this error:~~ <details> ``` error: unresolved link to `S::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:19:6 | 19 | /// [S::A] | ^^^^ | = note: this link partially resolves to the struct `S`, = note: `S` has no field, variant, or associated item named `A` ``` but I'm not sure how better to word it. I ended up going with 'no `A` in `S`' to match `rustc_resolve` but that seems terse as well. </details> This now says ``` error: unresolved link to `S::A` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:17:6 | 17 | /// [S::A] | ^^^^ | = note: the struct `S` has no field or associated item named `A` ``` which I think looks pretty good :) 4. This is minor, but it would be nice to say that `path` wasn't found instead of the full thing: ``` error: unresolved link to `path::to::nonexistent::module` --> /home/joshua/rustc/src/test/rustdoc-ui/intra-link-errors.rs:8:6 | 8 | /// [path::to::nonexistent::module] | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``` It will now look at most 3 paths up (so it reports `path::to` as not in scope), but it doesn't work with arbitrarily many paths. </details> ~~I recommend only reviewing the last few commits - the first 7 are all from rust-lang#74489.~~ Rebased so that only the relevant commits are shown. Let me know if I should squash the history some more. r? `@estebank`

Veetaha added the C-bug Category: This is a bug. label Aug 29, 2020

jonas-schievink added A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Aug 29, 2020

jyn514 self-assigned this Aug 29, 2020

jyn514 mentioned this issue Aug 29, 2020

Fix intra-doc links on pub re-exports #76082

Merged

jyn514 mentioned this issue Aug 30, 2020

Improve suggestions for broken intra-doc links #75756

Merged

jyn514 closed this as completed Sep 8, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Intra-doc links are unresolved on `pub use _ as _` items #76073

Intra-doc links are unresolved on `pub use _ as _` items #76073

Veetaha commented Aug 29, 2020 •

edited

Loading

jyn514 commented Aug 29, 2020

jyn514 commented Aug 29, 2020

jyn514 commented Aug 29, 2020

jyn514 commented Aug 29, 2020

Veetaha commented Aug 29, 2020 •

edited

Loading

jyn514 commented Aug 29, 2020

Veetaha commented Aug 29, 2020

jyn514 commented Sep 8, 2020

Intra-doc links are unresolved on pub use _ as _ items #76073

Intra-doc links are unresolved on pub use _ as _ items #76073

Comments

Veetaha commented Aug 29, 2020 • edited Loading

Meta

jyn514 commented Aug 29, 2020

jyn514 commented Aug 29, 2020

jyn514 commented Aug 29, 2020

jyn514 commented Aug 29, 2020

Veetaha commented Aug 29, 2020 • edited Loading

jyn514 commented Aug 29, 2020

Veetaha commented Aug 29, 2020

jyn514 commented Sep 8, 2020

Intra-doc links are unresolved on `pub use _ as _` items #76073

Intra-doc links are unresolved on `pub use _ as _` items #76073

Veetaha commented Aug 29, 2020 •

edited

Loading

Veetaha commented Aug 29, 2020 •

edited

Loading