Rollup merge of rust-lang#59717 - Reconcyl:master, r=steveklabnik

improve docs for std::hint::unreachable_unchecked()

Fixes rust-lang#59549

src/libcore/hint.rs

@@ -21,11 +21,10 @@ use intrinsics;
 /// difficult-to-debug problems.
 ///
 /// Use this function only when you can prove that the code will never call it.
+/// Otherwise, consider using the [`unreachable!`] macro, which does not allow
+/// optimizations but will panic when executed.
 ///
-/// The [`unreachable!()`] macro is the safe counterpart of this function, which
-/// will panic instead when executed.
-///
-/// [`unreachable!()`]: ../macro.unreachable.html
+/// [`unreachable!`]: ../macro.unreachable.html
 ///
 /// # Example
 ///