Auto merge of rust-lang#75815 - jyn514:ambiguous-primitives, r=guillaumegomez

Report an ambiguity if both modules and primitives are in scope for intra-doc links

Closes rust-lang#75381

- Add a new `prim@` disambiguator, since both modules and primitives are in the same namespace
- Refactor `report_ambiguity` into a closure

Additionally, I noticed that rustdoc would previously allow `[struct@char]` if `char` resolved to a primitive (not if it had a DefId). I fixed that and added a test case.

I also need to update libstd to use `prim@char` instead of `type@char`. If possible I would also like to refactor `ambiguity_error` to use `Disambiguator` instead of its own hand-rolled match - that ran into issues with `prim@` (I updated one and not the other) and it would be better for them to be in sync.

Author: bors

alloc/src/string.rs

@@ -268,8 +268,8 @@ use crate::vec::Vec;
 ///
 /// Here, there's no need to allocate more memory inside the loop.
 ///
-/// [`str`]: type@str
-/// [`&str`]: type@str
+/// [`str`]: prim@str
+/// [`&str`]: prim@str
 /// [`Deref`]: core::ops::Deref
 /// [`as_str()`]: String::as_str
 #[derive(PartialOrd, Eq, Ord)]
@@ -296,7 +296,7 @@ pub struct String {
 ///
 /// [`Utf8Error`]: core::str::Utf8Error
 /// [`std::str`]: core::str
-/// [`&str`]: str
+/// [`&str`]: prim@str
 /// [`utf8_error`]: Self::utf8_error
 ///
 /// # Examples
@@ -472,7 +472,7 @@ impl String {
     ///
     /// [`from_utf8_unchecked`]: String::from_utf8_unchecked
     /// [`Vec<u8>`]: crate::vec::Vec
-    /// [`&str`]: str
+    /// [`&str`]: prim@str
     /// [`into_bytes`]: String::into_bytes
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1576,6 +1576,8 @@ impl String {
     ///
     /// This will drop any excess capacity.
     ///
+    /// [`str`]: prim@str
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -1644,7 +1646,7 @@ impl FromUtf8Error {
     /// on using it.
     ///
     /// [`std::str`]: core::str
-    /// [`&str`]: str
+    /// [`&str`]: prim@str
     ///
     /// # Examples
     ///

core/src/str/mod.rs

@@ -476,6 +476,7 @@ Section: Iterators
 /// This struct is created by the [`chars`] method on [`str`].
 /// See its documentation for more.
 ///
+/// [`char`]: prim@char
 /// [`chars`]: str::chars
 #[derive(Clone)]
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -673,6 +674,7 @@ impl<'a> Chars<'a> {
 /// This struct is created by the [`char_indices`] method on [`str`].
 /// See its documentation for more.
 ///
+/// [`char`]: prim@char
 /// [`char_indices`]: str::char_indices
 #[derive(Clone, Debug)]
 #[stable(feature = "rust1", since = "1.0.0")]
@@ -2270,6 +2272,8 @@ impl str {
     /// This length is in bytes, not [`char`]s or graphemes. In other words,
     /// it may not be what a human considers the length of the string.
     ///
+    /// [`char`]: prim@char
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -2791,7 +2795,9 @@ impl str {
     /// assert_eq!(None, chars.next());
     /// ```
     ///
-    /// Remember, [`char`]s may not match your human intuition about characters:
+    /// Remember, [`char`]s may not match your intuition about characters:
+    ///
+    /// [`char`]: prim@char
     ///
     /// ```
     /// let y = "y̆";
@@ -2842,7 +2848,9 @@ impl str {
     /// assert_eq!(None, char_indices.next());
     /// ```
     ///
-    /// Remember, [`char`]s may not match your human intuition about characters:
+    /// Remember, [`char`]s may not match your intuition about characters:
+    ///
+    /// [`char`]: prim@char
     ///
     /// ```
     /// let yes = "y̆es";
@@ -3053,6 +3061,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -3079,6 +3088,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -3104,6 +3114,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -3132,6 +3143,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -3179,6 +3191,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -3225,6 +3238,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3344,6 +3358,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -3383,6 +3398,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3434,6 +3450,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// Equivalent to [`split`], except that the trailing substring
@@ -3478,6 +3495,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// Equivalent to [`split`], except that the trailing substring is
@@ -3526,6 +3544,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3578,6 +3597,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3666,6 +3686,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3702,6 +3723,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3743,6 +3765,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -3785,6 +3808,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Iterator behavior
@@ -4003,6 +4027,7 @@ impl str {
     /// The [pattern] can be a [`char`], a slice of [`char`]s, or a function
     /// or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -4050,6 +4075,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Text directionality
@@ -4094,6 +4120,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -4121,6 +4148,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Examples
@@ -4147,6 +4175,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Text directionality
@@ -4195,6 +4224,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Text directionality
@@ -4231,6 +4261,7 @@ impl str {
     /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
     /// function or closure that determines if a character matches.
     ///
+    /// [`char`]: prim@char
     /// [pattern]: self::pattern
     ///
     /// # Text directionality

std/src/error.rs

@@ -296,6 +296,8 @@ impl From<String> for Box<dyn Error> {
 impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a> {
     /// Converts a [`str`] into a box of dyn [`Error`] + [`Send`] + [`Sync`].
     ///
+    /// [`str`]: prim@str
+    ///
     /// # Examples
     ///
     /// ```
@@ -317,6 +319,8 @@ impl<'a> From<&str> for Box<dyn Error + Send + Sync + 'a> {
 impl From<&str> for Box<dyn Error> {
     /// Converts a [`str`] into a box of dyn [`Error`].
     ///
+    /// [`str`]: prim@str
+    ///
     /// # Examples
     ///
     /// ```

std/src/ffi/c_str.rs

@@ -69,7 +69,7 @@ use crate::sys;
 /// extern functions. See the documentation for that function for a
 /// discussion on ensuring the lifetime of the raw pointer.
 ///
-/// [`&str`]: str
+/// [`&str`]: prim@str
 /// [slice.as_ptr]: ../primitive.slice.html#method.as_ptr
 /// [slice.len]: ../primitive.slice.html#method.len
 /// [`Deref`]: ops::Deref
@@ -180,7 +180,7 @@ pub struct CString {
 /// println!("string: {}", my_string_safe());
 /// ```
 ///
-/// [`&str`]: str
+/// [`&str`]: prim@str
 #[derive(Hash)]
 #[stable(feature = "rust1", since = "1.0.0")]
 // FIXME:
@@ -1351,7 +1351,7 @@ impl CStr {
     /// function will return the corresponding [`&str`] slice. Otherwise,
     /// it will return an error with details of where UTF-8 validation failed.
     ///
-    /// [`&str`]: str
+    /// [`&str`]: prim@str
     ///
     /// # Examples
     ///
@@ -1379,6 +1379,7 @@ impl CStr {
     /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a
     /// [`Cow`]`::`[`Owned`]`(`[`String`]`)` with the result.
     ///
+    /// [`str`]: prim@str
     /// [`Borrowed`]: Cow::Borrowed
     /// [`Owned`]: Cow::Owned
     /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER

std/src/io/mod.rs

@@ -480,7 +480,7 @@ where
 /// ```
 ///
 /// [`read()`]: Read::read
-/// [`&str`]: str
+/// [`&str`]: prim@str
 /// [`std::io`]: self
 /// [`File`]: crate::fs::File
 /// [slice]: ../../std/primitive.slice.html

std/src/lib.rs

@@ -172,6 +172,7 @@
 //! [`Vec<T>`]: vec::Vec
 //! [`atomic`]: sync::atomic
 //! [`for`]: ../book/ch03-05-control-flow.html#looping-through-a-collection-with-for
+//! [`str`]: prim@str
 //! [`mpsc`]: sync::mpsc
 //! [`std::cmp`]: cmp
 //! [`std::slice`]: slice