Apply 16 commits (squashed)

---------- Fix spacing for links inside code blocks, and improve link tooltips in alloc::fmt ---------- Fix spacing for links inside code blocks, and improve link tooltips in alloc::{rc, sync} ---------- Fix spacing for links inside code blocks, and improve link tooltips in alloc::string ---------- Fix spacing for links inside code blocks in alloc::vec ---------- Fix spacing for links inside code blocks in core::option ---------- Fix spacing for links inside code blocks, and improve a few link tooltips in core::result ---------- Fix spacing for links inside code blocks in core::{iter::{self, iterator}, stream::stream, poll} ---------- Fix spacing for links inside code blocks, and improve a few link tooltips in std::{fs, path} ---------- Fix spacing for links inside code blocks in std::{collections, time} ---------- Fix spacing for links inside code blocks in and make formatting of `&str`-like types consistent in std::ffi::{c_str, os_str} ---------- Fix spacing for links inside code blocks, and improve link tooltips in std::ffi ---------- Fix spacing for links inside code blocks, and improve a few link tooltips in std::{io::{self, buffered::{bufreader, bufwriter}, cursor, util}, net::{self, addr}} ---------- Fix typo in link to `into` for `OsString` docs ---------- Remove tooltips that will probably become redundant in the future ---------- Apply suggestions from code review Replacing `…std/primitive.reference.html` paths with just `reference` Co-authored-by: Joshua Nelson <github@jyn.dev> ---------- Also replace `…std/primitive.reference.html` paths with just `reference` in `core::pin`
rust-lang · Sep 25, 2021 · 67065fe · 67065fe
1 parent 7b0e554
commit 67065fe
Show file tree

Hide file tree

Showing 26 changed files with 226 additions and 235 deletions.
diff --git a/library/alloc/src/fmt.rs b/library/alloc/src/fmt.rs
@@ -348,7 +348,7 @@
 //! provides some helper methods.
 //!
 //! Additionally, the return value of this function is [`fmt::Result`] which is a
-//! type alias of [`Result`]`<(), `[`std::fmt::Error`]`>`. Formatting implementations
+//! type alias of <code>[Result]<(), [std::fmt::Error]></code>. Formatting implementations
 //! should ensure that they propagate errors from the [`Formatter`] (e.g., when
 //! calling [`write!`]). However, they should never return errors spuriously. That
 //! is, a formatting implementation must and may only return an error if the
@@ -505,23 +505,19 @@
 //! it would internally pass around this structure until it has been determined
 //! where output should go to.
 //!
-//! [`fmt::Result`]: Result
-//! [`Result`]: core::result::Result
-//! [`std::fmt::Error`]: Error
-//! [`write!`]: core::write
-//! [`write`]: core::write
-//! [`format!`]: crate::format
-//! [`to_string`]: crate::string::ToString
-//! [`writeln!`]: core::writeln
+//! [`fmt::Result`]: Result "fmt::Result"
+//! [Result]: core::result::Result "std::result::Result"
+//! [std::fmt::Error]: Error "fmt::Error"
+//! [`write`]: write() "fmt::write"
+//! [`to_string`]: crate::string::ToString::to_string "ToString::to_string"
 //! [`write_fmt`]: ../../std/io/trait.Write.html#method.write_fmt
 //! [`std::io::Write`]: ../../std/io/trait.Write.html
-//! [`print!`]: ../../std/macro.print.html
-//! [`println!`]: ../../std/macro.println.html
-//! [`eprint!`]: ../../std/macro.eprint.html
-//! [`eprintln!`]: ../../std/macro.eprintln.html
-//! [`format_args!`]: core::format_args
-//! [`fmt::Arguments`]: Arguments
-//! [`format`]: crate::format
+//! [`print!`]: ../../std/macro.print.html "print!"
+//! [`println!`]: ../../std/macro.println.html "println!"
+//! [`eprint!`]: ../../std/macro.eprint.html "eprint!"
+//! [`eprintln!`]: ../../std/macro.eprintln.html "eprintln!"
+//! [`fmt::Arguments`]: Arguments "fmt::Arguments"
+//! [`format`]: format() "fmt::format"
 
 #![stable(feature = "rust1", since = "1.0.0")]
 

diff --git a/library/alloc/src/rc.rs b/library/alloc/src/rc.rs
@@ -781,9 +781,7 @@ impl<T: ?Sized> Rc<T> {
  /// Consumes the `Rc`, returning the wrapped pointer.
  ///
  /// To avoid a memory leak the pointer must be converted back to an `Rc` using
- /// [`Rc::from_raw`][from_raw].
- ///
- /// [from_raw]: Rc::from_raw
+ /// [`Rc::from_raw`].
  ///
  /// # Examples
  ///
@@ -834,7 +832,7 @@ impl<T: ?Sized> Rc<T> {
  /// and alignment as `T`. This is trivially true if `U` is `T`.
  /// Note that if `U` is not `T` but has the same size and alignment, this is
  /// basically like transmuting references of different types. See
- /// [`mem::transmute`][transmute] for more information on what
+ /// [`mem::transmute`] for more information on what
  /// restrictions apply in this case.
  ///
  /// The user of `from_raw` has to make sure a specific value of `T` is only
@@ -844,7 +842,6 @@ impl<T: ?Sized> Rc<T> {
  /// even if the returned `Rc<T>` is never accessed.
  ///
  /// [into_raw]: Rc::into_raw
- /// [transmute]: core::mem::transmute
  ///
  /// # Examples
  ///
@@ -1086,8 +1083,6 @@ impl<T: ?Sized> Rc<T> {
  /// assert!(Rc::ptr_eq(&five, &same_five));
  /// assert!(!Rc::ptr_eq(&five, &other_five));
  /// ```
- ///
- /// [`ptr::eq`]: core::ptr::eq
  pub fn ptr_eq(this: &Self, other: &Self) -> bool {
  this.ptr.as_ptr() == other.ptr.as_ptr()
  }
@@ -1993,7 +1988,7 @@ impl<T, I: iter::TrustedLen<Item = T>> ToRcSlice<T> for I {
 
 /// `Weak` is a version of [`Rc`] that holds a non-owning reference to the
 /// managed allocation. The allocation is accessed by calling [`upgrade`] on the `Weak`
-/// pointer, which returns an [`Option`]`<`[`Rc`]`<T>>`.
+/// pointer, which returns an <code>[Option]<[Rc]\<T>></code>.
 ///
 /// Since a `Weak` reference does not count towards ownership, it will not
 /// prevent the value stored in the allocation from being dropped, and `Weak` itself makes no
@@ -2090,7 +2085,7 @@ impl<T: ?Sized> Weak<T> {
  /// // assert_eq!("hello", unsafe { &*weak.as_ptr() });
  /// ```
  ///
- /// [`null`]: core::ptr::null
+ /// [`null`]: ptr::null
  #[stable(feature = "rc_as_ptr", since = "1.45.0")]
  pub fn as_ptr(&self) -> *const T {
  let ptr: *mut RcBox<T> = NonNull::as_ptr(self.ptr);
@@ -2317,8 +2312,6 @@ impl<T: ?Sized> Weak<T> {
  /// let third = Rc::downgrade(&third_rc);
  /// assert!(!first.ptr_eq(&third));
  /// ```
- ///
- /// [`ptr::eq`]: core::ptr::eq
  #[inline]
  #[stable(feature = "weak_ptr_eq", since = "1.39.0")]
  pub fn ptr_eq(&self, other: &Self) -> bool {
@@ -2400,7 +2393,6 @@ impl<T> Default for Weak<T> {
  /// Constructs a new `Weak<T>`, without allocating any memory.
  /// Calling [`upgrade`] on the return value always gives [`None`].
  ///
- /// [`None`]: Option
  /// [`upgrade`]: Weak::upgrade
  ///
  /// # Examples

diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs
@@ -79,7 +79,7 @@ use crate::vec::Vec;
 ///
 /// # Examples
 ///
-/// You can create a `String` from [a literal string][`str`] with [`String::from`]:
+/// You can create a `String` from [a literal string][`&str`] with [`String::from`]:
 ///
 /// [`String::from`]: From::from
 ///
@@ -128,7 +128,7 @@ use crate::vec::Vec;
 /// println!("The first letter of s is {}", s[0]); // ERROR!!!
 /// ```
 ///
-/// [`OsString`]: ../../std/ffi/struct.OsString.html
+/// [`OsString`]: ../../std/ffi/struct.OsString.html "ffi::OsString"
 ///
 /// Indexing is intended to be a constant-time operation, but UTF-8 encoding
 /// does not allow us to do this. Furthermore, it's not clear what sort of
@@ -141,7 +141,7 @@ use crate::vec::Vec;
 ///
 /// # Deref
 ///
-/// `String`s implement [`Deref`]`<Target=str>`, and so inherit all of [`str`]'s
+/// `String` implements <code>[Deref]<Target = [str]></code>, and so inherits all of [`str`]'s
 /// methods. In addition, this means that you can pass a `String` to a
 /// function which takes a [`&str`] by using an ampersand (`&`):
 ///
@@ -182,7 +182,7 @@ use crate::vec::Vec;
 /// to explicitly extract the string slice containing the string. The second
 /// way changes `example_func(&example_string);` to
 /// `example_func(&*example_string);`. In this case we are dereferencing a
-/// `String` to a [`str`][`&str`], then referencing the [`str`][`&str`] back to
+/// `String` to a [`str`], then referencing the [`str`] back to
 /// [`&str`]. The second way is more idiomatic, however both work to do the
 /// conversion explicitly rather than relying on the implicit conversion.
 ///
@@ -282,9 +282,11 @@ use crate::vec::Vec;
 ///
 /// Here, there's no need to allocate more memory inside the loop.
 ///
-/// [`str`]: prim@str
-/// [`&str`]: prim@str
-/// [`Deref`]: core::ops::Deref
+/// [str]: prim@str "str"
+/// [`str`]: prim@str "str"
+/// [`&str`]: prim@str "&str"
+/// [Deref]: core::ops::Deref "ops::Deref"
+/// [`Deref`]: core::ops::Deref "ops::Deref"
 /// [`as_str()`]: String::as_str
 #[derive(PartialOrd, Eq, Ord)]
 #[cfg_attr(not(test), rustc_diagnostic_item = "string_type")]
@@ -308,10 +310,10 @@ pub struct String {
 /// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error`
 /// through the [`utf8_error`] method.
 ///
-/// [`Utf8Error`]: core::str::Utf8Error
-/// [`std::str`]: core::str
-/// [`&str`]: prim@str
-/// [`utf8_error`]: Self::utf8_error
+/// [`Utf8Error`]: str::Utf8Error "std::str::Utf8Error"
+/// [`std::str`]: core::str "std::str"
+/// [`&str`]: prim@str "&str"
+/// [`utf8_error`]: FromUtf8Error::utf8_error
 ///
 /// # Examples
 ///
@@ -487,8 +489,8 @@ impl String {
  /// with this error.
  ///
  /// [`from_utf8_unchecked`]: String::from_utf8_unchecked
- /// [`Vec<u8>`]: crate::vec::Vec
- /// [`&str`]: prim@str
+ /// [`Vec<u8>`]: crate::vec::Vec "Vec"
+ /// [`&str`]: prim@str "&str"
  /// [`into_bytes`]: String::into_bytes
  #[inline]
  #[stable(feature = "rust1", since = "1.0.0")]
@@ -524,7 +526,7 @@ impl String {
  /// it's already valid UTF-8, we don't need a new allocation. This return
  /// type allows us to handle both cases.
  ///
- /// [`Cow<'a, str>`]: crate::borrow::Cow
+ /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow"
  ///
  /// # Examples
  ///
@@ -625,7 +627,7 @@ impl String {
  /// conversion requires a memory allocation.
  ///
  /// [`from_utf8_lossy`]: String::from_utf8_lossy
- /// [`Cow<'a, str>`]: crate::borrow::Cow
+ /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow"
  /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER
  ///
  /// # Examples
@@ -1721,11 +1723,11 @@ impl String {
  unsafe { self.as_mut_vec() }.splice((start, end), replace_with.bytes());
  }
 
- /// Converts this `String` into a [`Box`]`<`[`str`]`>`.
+ /// Converts this `String` into a <code>[Box]<[str]></code>.
  ///
  /// This will drop any excess capacity.
  ///
- /// [`str`]: prim@str
+ /// [str]: prim@str "str"
  ///
  /// # Examples
  ///
@@ -1795,8 +1797,8 @@ impl FromUtf8Error {
  /// an analogue to `FromUtf8Error`. See its documentation for more details
  /// on using it.
  ///
- /// [`std::str`]: core::str
- /// [`&str`]: prim@str
+ /// [`std::str`]: core::str "std::str"
+ /// [`&str`]: prim@str "&str"
  ///
  /// # Examples
  ///
@@ -2319,7 +2321,7 @@ impl ops::DerefMut for String {
 ///
 /// This alias exists for backwards compatibility, and may be eventually deprecated.
 ///
-/// [`Infallible`]: core::convert::Infallible
+/// [`Infallible`]: core::convert::Infallible "convert::Infallible"
 #[stable(feature = "str_parse_error", since = "1.5.0")]
 pub type ParseError = core::convert::Infallible;
 
@@ -2606,7 +2608,7 @@ impl<'a> From<&'a str> for Cow<'a, str> {
  /// assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant"));
  /// ```
  ///
- /// [`Borrowed`]: crate::borrow::Cow::Borrowed
+ /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed"
  #[inline]
  fn from(s: &'a str) -> Cow<'a, str> {
  Cow::Borrowed(s)
@@ -2629,7 +2631,7 @@ impl<'a> From<String> for Cow<'a, str> {
  /// assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2));
  /// ```
  ///
- /// [`Owned`]: crate::borrow::Cow::Owned
+ /// [`Owned`]: crate::borrow::Cow::Owned "borrow::Cow::Owned"
  #[inline]
  fn from(s: String) -> Cow<'a, str> {
  Cow::Owned(s)
@@ -2651,7 +2653,7 @@ impl<'a> From<&'a String> for Cow<'a, str> {
  /// assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant"));
  /// ```
  ///
- /// [`Borrowed`]: crate::borrow::Cow::Borrowed
+ /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed"
  #[inline]
  fn from(s: &'a String) -> Cow<'a, str> {
  Cow::Borrowed(s.as_str())

diff --git a/library/alloc/src/sync.rs b/library/alloc/src/sync.rs
@@ -99,8 +99,8 @@ macro_rules! acquire {
 /// first: after all, isn't the point of `Arc<T>` thread safety? The key is
 /// this: `Arc<T>` makes it thread safe to have multiple ownership of the same
 /// data, but it doesn't add thread safety to its data. Consider
-/// `Arc<`[`RefCell<T>`]`>`. [`RefCell<T>`] isn't [`Sync`], and if `Arc<T>` was always
-/// [`Send`], `Arc<`[`RefCell<T>`]`>` would be as well. But then we'd have a problem:
+/// <code>Arc<[RefCell\<T>]></code>. [`RefCell<T>`] isn't [`Sync`], and if `Arc<T>` was always
+/// [`Send`], <code>Arc<[RefCell\<T>]></code> would be as well. But then we'd have a problem:
 /// [`RefCell<T>`] is not thread safe; it keeps track of the borrowing count using
 /// non-atomic operations.
 ///
@@ -176,6 +176,7 @@ macro_rules! acquire {
 /// [deref]: core::ops::Deref
 /// [downgrade]: Arc::downgrade
 /// [upgrade]: Weak::upgrade
+/// [RefCell\<T>]: core::cell::RefCell
 /// [`RefCell<T>`]: core::cell::RefCell
 /// [`std::sync`]: ../../std/sync/index.html
 /// [`Arc::clone(&from)`]: Arc::clone
@@ -206,7 +207,7 @@ macro_rules! acquire {
 ///
 /// Sharing a mutable [`AtomicUsize`]:
 ///
-/// [`AtomicUsize`]: core::sync::atomic::AtomicUsize
+/// [`AtomicUsize`]: core::sync::atomic::AtomicUsize "sync::atomic::AtomicUsize"
 ///
 /// ```no_run
 /// use std::sync::Arc;
@@ -262,7 +263,7 @@ impl<T: ?Sized> Arc<T> {
 
 /// `Weak` is a version of [`Arc`] that holds a non-owning reference to the
 /// managed allocation. The allocation is accessed by calling [`upgrade`] on the `Weak`
-/// pointer, which returns an [`Option`]`<`[`Arc`]`<T>>`.
+/// pointer, which returns an <code>[Option]<[Arc]\<T>></code>.
 ///
 /// Since a `Weak` reference does not count towards ownership, it will not
 /// prevent the value stored in the allocation from being dropped, and `Weak` itself makes no
@@ -476,7 +477,7 @@ impl<T> Arc<T> {
  /// assert_eq!(*zero, 0)
  /// ```
  ///
- /// [zeroed]: ../../std/mem/union.MaybeUninit.html#method.zeroed
+ /// [zeroed]: mem::MaybeUninit::zeroed
  #[cfg(not(no_global_oom_handling))]
  #[unstable(feature = "new_uninit", issue = "63291")]
  pub fn new_zeroed() -> Arc<mem::MaybeUninit<T>> {
@@ -684,7 +685,7 @@ impl<T> Arc<[T]> {
  /// assert_eq!(*values, [0, 0, 0])
  /// ```
  ///
- /// [zeroed]: ../../std/mem/union.MaybeUninit.html#method.zeroed
+ /// [zeroed]: mem::MaybeUninit::zeroed
  #[cfg(not(no_global_oom_handling))]
  #[unstable(feature = "new_uninit", issue = "63291")]
  pub fn new_zeroed_slice(len: usize) -> Arc<[mem::MaybeUninit<T>]> {
@@ -712,7 +713,7 @@ impl<T> Arc<mem::MaybeUninit<T>> {
  /// Calling this when the content is not yet fully initialized
  /// causes immediate undefined behavior.
  ///
- /// [`MaybeUninit::assume_init`]: ../../std/mem/union.MaybeUninit.html#method.assume_init
+ /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init
  ///
  /// # Examples
  ///
@@ -751,7 +752,7 @@ impl<T> Arc<[mem::MaybeUninit<T>]> {
  /// Calling this when the content is not yet fully initialized
  /// causes immediate undefined behavior.
  ///
- /// [`MaybeUninit::assume_init`]: ../../std/mem/union.MaybeUninit.html#method.assume_init
+ /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init
  ///
  /// # Examples
  ///
@@ -1086,7 +1087,7 @@ impl<T: ?Sized> Arc<T> {
  /// assert!(!Arc::ptr_eq(&five, &other_five));
  /// ```
  ///
- /// [`ptr::eq`]: core::ptr::eq
+ /// [`ptr::eq`]: core::ptr::eq "ptr::eq"
  pub fn ptr_eq(this: &Self, other: &Self) -> bool {
  this.ptr.as_ptr() == other.ptr.as_ptr()
  }
@@ -1714,7 +1715,7 @@ impl<T: ?Sized> Weak<T> {
  /// // assert_eq!("hello", unsafe { &*weak.as_ptr() });
  /// ```
  ///
- /// [`null`]: core::ptr::null
+ /// [`null`]: core::ptr::null "ptr::null"
  #[stable(feature = "weak_into_raw", since = "1.45.0")]
  pub fn as_ptr(&self) -> *const T {
  let ptr: *mut ArcInner<T> = NonNull::as_ptr(self.ptr);
@@ -1806,7 +1807,6 @@ impl<T: ?Sized> Weak<T> {
  /// [`new`]: Weak::new
  /// [`into_raw`]: Weak::into_raw
  /// [`upgrade`]: Weak::upgrade
- /// [`forget`]: std::mem::forget
  #[stable(feature = "weak_into_raw", since = "1.45.0")]
  pub unsafe fn from_raw(ptr: *const T) -> Self {
  // See Weak::as_ptr for context on how the input pointer is derived.
@@ -1982,7 +1982,7 @@ impl<T: ?Sized> Weak<T> {
  /// assert!(!first.ptr_eq(&third));
  /// ```
  ///
- /// [`ptr::eq`]: core::ptr::eq
+ /// [`ptr::eq`]: core::ptr::eq "ptr::eq"
  #[inline]
  #[stable(feature = "weak_ptr_eq", since = "1.39.0")]
  pub fn ptr_eq(&self, other: &Self) -> bool {