From 5128fcb1991d35c0e23d2622504d76d33b480825 Mon Sep 17 00:00:00 2001
From: Zac Harrold <zac@harrold.com.au>
Date: Mon, 29 Jun 2026 14:58:44 +1000
Subject: [PATCH] Note where and why documentation hard-links are used

Also link back to a relevant issue to track possible changes in functionality.
---
 library/alloc/src/io/error.rs | 3 +++
 library/core/src/io/cursor.rs | 2 ++
 library/core/src/io/error.rs  | 6 ++++++
 3 files changed, 11 insertions(+)

diff --git a/library/alloc/src/io/error.rs b/library/alloc/src/io/error.rs
index 8053e73917c7f..eb02664ee7e46 100644
--- a/library/alloc/src/io/error.rs
+++ b/library/alloc/src/io/error.rs
@@ -55,6 +55,7 @@ impl Error {
     /// originate from the OS itself. It is a shortcut for [`Error::new`][new]
     /// with [`ErrorKind::Other`].
     ///
+    // FIXME(#74481): Hard-links required to link from `alloc` to `std` for incoherent method
     /// [new]: struct.Error.html#method.new
     ///
     /// # Examples
@@ -84,6 +85,7 @@ impl Error {
     /// then this function will return [`Some`],
     /// otherwise it will return [`None`].
     ///
+    // FIXME(#74481): Hard-links required to link from `alloc` to `std` for incoherent method
     /// [new]: struct.Error.html#method.new
     /// [other]: struct.Error.html#method.other
     ///
@@ -141,6 +143,7 @@ impl Error {
     /// `Box<dyn Error + Sync + Send>::downcast` on the custom boxed error, returned by
     /// [`Error::into_inner`][into_inner].
     ///
+    // FIXME(#74481): Hard-links required to link from `alloc` to `std` for incoherent method
     /// [into_inner]: struct.Error.html#method.into_inner
     ///
     /// # Examples
diff --git a/library/core/src/io/cursor.rs b/library/core/src/io/cursor.rs
index ebbec6c5e8210..24d3bfc67b988 100644
--- a/library/core/src/io/cursor.rs
+++ b/library/core/src/io/cursor.rs
@@ -16,6 +16,7 @@
 /// code, but use an in-memory buffer in our tests. We can do this with
 /// `Cursor`:
 ///
+// FIXME(#74481): Hard-links required to link from `core` to `std`
 /// [bytes]: crate::slice "slice"
 /// [`File`]: ../../std/fs/struct.File.html
 /// [`Read`]: ../../std/io/trait.Read.html
@@ -80,6 +81,7 @@ impl<T> Cursor<T> {
     /// is not empty. So writing to cursor starts with overwriting [`Vec`]
     /// content, not with appending to it.
     ///
+    // FIXME(#74481): Hard-links required to link from `core` to `alloc`
     /// [`Vec`]: ../../alloc/vec/struct.Vec.html
     ///
     /// # Examples
diff --git a/library/core/src/io/error.rs b/library/core/src/io/error.rs
index f9e45313be53d..2d15307daf153 100644
--- a/library/core/src/io/error.rs
+++ b/library/core/src/io/error.rs
@@ -45,6 +45,7 @@ use crate::{error, fmt, result};
 /// will generally use `io::Result` instead of shadowing the [prelude]'s import
 /// of [`core::result::Result`][`Result`].
 ///
+// FIXME(#74481): Hard-links required to link from `core` to `std`
 /// [`std::io`]: ../../std/io/index.html
 /// [`io::Error`]: Error
 /// [`Result`]: crate::result::Result
@@ -76,6 +77,7 @@ pub type Result<T> = result::Result<T, Error>;
 /// `Error` can be created with crafted error messages and a particular value of
 /// [`ErrorKind`].
 ///
+// FIXME(#74481): Hard-links required to link from `core` to `std`
 /// [Read]: ../../std/io/trait.Read.html
 /// [Write]: ../../std/io/trait.Write.html
 /// [Seek]: ../../std/io/trait.Seek.html
@@ -171,6 +173,7 @@ pub struct SimpleMessage {
 /// Contrary to [`Error::new`][new], this macro does not allocate and can be used in
 /// `const` contexts.
 ///
+// FIXME(#74481): Hard-links required to link from `core` to `alloc` for incoherent method
 /// [new]: ../../alloc/io/struct.Error.html#method.new
 ///
 /// # Example
@@ -286,6 +289,7 @@ impl Error {
     /// [`from_raw_os_error`][from_raw_os_error], then this function will return [`Some`], otherwise
     /// it will return [`None`].
     ///
+    // FIXME(#74481): Hard-links required to link from `core` to `std` for incoherent method
     /// [last_os_error]: ../../std/io/struct.Error.html#method.last_os_error
     /// [from_raw_os_error]: ../../std/io/struct.Error.html#method.from_raw_os_error
     ///
@@ -366,6 +370,7 @@ impl Error {
     /// If this [`Error`] was constructed via [`new`][new] then this function will
     /// return [`Some`], otherwise it will return [`None`].
     ///
+    // FIXME(#74481): Hard-links required to link from `core` to `std`
     /// [new]: ../../alloc/io/struct.Error.html#method.new
     ///
     /// # Examples
@@ -441,6 +446,7 @@ impl Error {
     /// it will be a value inferred from the system's error encoding.
     /// See [`last_os_error`][last_os_error] for more details.
     ///
+    // FIXME(#74481): Hard-links required to link from `core` to `std`
     /// [last_os_error]: ../../std/io/struct.Error.html#method.last_os_error
     ///
     /// # Examples