Fix intra-doc links for associated items by jyn514 · Pull Request #74489 · rust-lang/rust (original) (raw)

Conversation

This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters

[ Show hidden characters]({{ revealButtonHref }})

jyn514 added T-rustdoc

Relevant to the rustdoc team, which will review and decide on the PR/issue.

C-bug

Category: This is a bug.

A-intra-doc-links

Area: Intra-doc links, the ability to link to items in docs by name

labels

Jul 18, 2020

jyn514 added S-waiting-on-author

Status: This is awaiting some action (such as code changes or more information) from the author.

and removed S-waiting-on-review

Status: Awaiting review from the assignee but also interested parties.

labels

Jul 18, 2020

jyn514 added a commit to jyn514/rust that referenced this pull request

Jul 20, 2020

…solution failures

The version of rust-lang#74489 that warns about ambiguity errors

bors added S-waiting-on-bors

Status: Waiting on bors to run and complete tests. Bors will change the label on completion.

and removed S-waiting-on-author

Status: This is awaiting some action (such as code changes or more information) from the author.

labels

Aug 23, 2020

This was referenced

Aug 24, 2020

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request

Sep 12, 2020

…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 Errors 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:

/// [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`

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

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 `\]`

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

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

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`

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]
  |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

bors added a commit to rust-lang-ci/rust that referenced this pull request

Sep 12, 2020

…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 Errors 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:

/// [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`

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

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 `\]`

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

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

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`

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]
  |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

This was referenced

Sep 18, 2020

This was referenced

Oct 3, 2020

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request

Feb 25, 2021

Convert core/num/mod.rs to intra-doc links

Helps with rust-lang#75080. This can't convert the associated constants MAX and MIN until rust-lang#74489 is merged.

r? @poliorcetics

JohnTitor added a commit to JohnTitor/rust that referenced this pull request

Mar 2, 2021

wip-sync pushed a commit to NetBSD/pkgsrc-wip that referenced this pull request

Apr 10, 2021

Pkgsrc changes:

• Remove one SunOS patch, apparently no longer needed.
• Adapt one patch for Darwin, adjust cargo checksum accordingly.
• Adjust bootstraps to version 1.50.0.

Version 1.51.0 (2021-03-25)

Language

• You can now parameterize items such as functions, traits, and structs by constant values in addition to by types and lifetimes. Also known as "const generics" E.g. you can now write the following. Note: Only values of primitive integers, bool, or char types are currently permitted.

  struct GenericArray<T, const LENGTH: usize> {
      inner: [T; LENGTH]
  }
  
  impl<T, const LENGTH: usize> GenericArray<T, LENGTH> {
      const fn last(&self) -> Option<&T> {
          if LENGTH == 0 {
              None
          } else {
              Some(&self.inner[LENGTH - 1])
          }
      }
  }

Compiler

• Added the -Csplit-debuginfo codegen option for macOS platforms. This option controls whether debug information is split across multiple files or packed into a single file. Note This option is unstable on other platforms.
• Added tier 3* support for aarch64_be-unknown-linux-gnu, aarch64-unknown-linux-gnu_ilp32, and aarch64_be-unknown-linux-gnu_ilp32 targets.
• Added tier 3 support for i386-unknown-linux-gnu and i486-unknown-linux-gnu targets.
• The target-cpu=native option will now detect individual features of CPUs.
• Rust now uses inline-asm for stack probes when used with LLVM 11.0.1+

* Refer to Rust's [platform support page][forge-platform-support] for more information on Rust's tiered platform support.

Libraries

• [Box::downcast is now also implemented for any `dyn Any + Send
  • Sync` object.]80945
• str now implements AsMut<str>.
• u64 and u128 now implement From<char>.
• Error is now implemented for &T where T implements Error.
• Poll::{map_ok, map_err} are now implemented for Poll<Option<Result<T, E>>>.
• unsigned_abs is now implemented for all signed integer types.
• io::Empty now implements io::Seek.
• rc::Weak<T> and sync::Weak<T>'s methods such as as_ptr are now implemented for T: ?Sized types.

Stabilized APIs

• Arc::decrement_strong_count
• Arc::increment_strong_count
• Once::call_once_force
• Peekable::next_if_eq
• Peekable::next_if
• Seek::stream_position
• array::IntoIter
• panic::panic_any
• ptr::addr_of!
• ptr::addr_of_mut!
• slice::fill_with
• slice::split_inclusive_mut
• slice::split_inclusive
• slice::strip_prefix
• slice::strip_suffix
• str::split_inclusive
• sync::OnceState
• task::Wake

Cargo

• Added the split-debuginfo profile option to control the -Csplit-debuginfo codegen option.
• Added the resolver field to Cargo.toml to enable the new feature resolver and CLI option behavior. Version 2 of the feature resolver will try to avoid unifying features of dependencies where that unification could be unwanted. Such as using the same dependency with a std feature in a build scripts and proc-macros, while using the no-std feature in the final binary. See the Cargo book documentation for more information on the feature.

Rustdoc

• Rustdoc will now include documentation for methods available from Deref traits.
• You can now provide a --default-theme flag which sets the default theme to use for documentation.

Various improvements to intra-doc links:

• You can link to non-path primitives such as slice.
• You can link to associated items.
• You can now include generic parameters when linking to items, like Vec<T>.

Misc

• You can now pass --include-ignored to tests (e.g. with cargo test -- --include-ignored) to include testing tests marked #[ignore].

Compatibility Notes

• WASI platforms no longer use the wasm-bindgen ABI, and instead use the wasm32 ABI.

• rustc no longer promotes division, modulo and indexing operations to const that could fail.

• The minimum version of glibc for the following platforms has been bumped to version 2.31 for the distributed artifacts.

  • armv5te-unknown-linux-gnueabi
  • sparc64-unknown-linux-gnu
  • thumbv7neon-unknown-linux-gnueabihf
  • armv7-unknown-linux-gnueabi
  • x86_64-unknown-linux-gnux32

Internal Only

• Consistently avoid constructing optimized MIR when not doing codegen

netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this pull request

May 26, 2021

Pkgsrc changes:

• Add support for the big-endian arm64 NetBSD target (aarch64_be).
• On NetBSD/i386, use the i586 (pentium) bootstrap kit variant in preference to i686.
• Adjust patches, re-compute line offsets, re-compute crate checksums.
• Remove a patch which was either integrated upstream and/or no longer applies.
• Bump bootstraps to 1.50.0.
• Move conditionals until after bsd.prefs.mk so that they work...
• Default to "dist" build target if cross-compiling, but allow also to override via rust.BUILD_TARGET.
• Allow overriding MAKE_JOBS_SAFE via rust.MAKE_JOBS_SAFE if you want a different trade-off between occasional breakage and performance.
• Adjust platform.mk according to work already done in wip/rust/
• Add a patch to optimize the install.sh script used to install binary bootstraps to not do so many forks; use case/esac and parameter expansion instead of grep, sed and cut.
• Drop building documentation for the binary bootstrap kits. This will also impact the lang/rust-bin package. For full documentation, build or install lang/rust as a package.

Upstream changes:

Version 1.51.0 (2021-03-25)

Language

• You can now parameterize items such as functions, traits, and structs by constant values in addition to by types and lifetimes. Also known as "const generics" E.g. you can now write the following. Note: Only values of primitive integers, bool, or char types are currently permitted.

  struct GenericArray<T, const LENGTH: usize> {
      inner: [T; LENGTH]
  }
  
  impl<T, const LENGTH: usize> GenericArray<T, LENGTH> {
      const fn last(&self) -> Option<&T> {
          if LENGTH == 0 {
              None
          } else {
              Some(&self.inner[LENGTH - 1])
          }
      }
  }

Compiler

• Added the -Csplit-debuginfo codegen option for macOS platforms. This option controls whether debug information is split across multiple files or packed into a single file. Note This option is unstable on other platforms.

• Added tier 3* support for aarch64_be-unknown-linux-gnu, aarch64-unknown-linux-gnu_ilp32, and aarch64_be-unknown-linux-gnu_ilp32 targets.

• Added tier 3 support for i386-unknown-linux-gnu and i486-unknown-linux-gnu targets.

• The target-cpu=native option will now detect individual features of CPUs.

* Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support.

Libraries

• [Box::downcast is now also implemented for any `dyn Any + Send
  • Sync` object.]80945
• str now implements AsMut<str>.
• u64 and u128 now implement From<char>.
• Error is now implemented for &T where T implements Error.
• Poll::{map_ok, map_err} are now implemented for Poll<Option<Result<T,E>>>.
• unsigned_abs is now implemented for all signed integer types.
• io::Empty now implements io::Seek.
• rc::Weak<T> and sync::Weak<T>'s methods such as as_ptr are now implemented for T: ?Sized types.
• Div and Rem by their NonZero variant is now implemented for all unsigned integers.

Stabilized APIs

• Arc::decrement_strong_count
• Arc::increment_strong_count
• Once::call_once_force
• Peekable::next_if_eq
• Peekable::next_if
• Seek::stream_position
• array::IntoIter
• panic::panic_any
• ptr::addr_of!
• ptr::addr_of_mut!
• slice::fill_with
• slice::split_inclusive_mut
• slice::split_inclusive
• slice::strip_prefix
• slice::strip_suffix
• str::split_inclusive
• sync::OnceState
• task::Wake
• VecDeque::range
• VecDeque::range_mut

Cargo

• Added the split-debuginfo profile option to control the -Csplit-debuginfo codegen option.
• Added the resolver field to Cargo.toml to enable the new feature resolver and CLI option behavior. Version 2 of the feature resolver will try to avoid unifying features of dependencies where that unification could be unwanted. Such as using the same dependency with a std feature in a build scripts and proc-macros, while using the no-std feature in the final binary. See the Cargo book documentation for more information on the feature.

Rustdoc

• Rustdoc will now include documentation for methods available from nested Deref traits.
• You can now provide a --default-theme flag which sets the default theme to use for documentation.

Various improvements to intra-doc links:

• You can link to non-path primitives such as slice.
• You can link to associated items.
• You can now include generic parameters when linking to items, like Vec<T>.

Misc

• You can now pass --include-ignored to tests (e.g. with cargo test -- --include-ignored) to include testing tests marked #[ignore].

Compatibility Notes

• WASI platforms no longer use the wasm-bindgen ABI, and instead use the wasm32 ABI.
• rustc no longer promotes division, modulo and indexing operations to const that could fail.
• The minimum version of glibc for the following platforms has been bumped to version 2.31 for the distributed artifacts.
  • armv5te-unknown-linux-gnueabi
  • sparc64-unknown-linux-gnu
  • thumbv7neon-unknown-linux-gnueabihf
  • armv7-unknown-linux-gnueabi
  • x86_64-unknown-linux-gnux32
• atomic::spin_loop_hint has been deprecated. It's recommended to use hint::spin_loop instead.

Internal Only

• Consistently avoid constructing optimized MIR when not doing codegen