From e4a259b5e480ea5b444384f9ff9cd862a46a9d16 Mon Sep 17 00:00:00 2001
From: Jan Behrens <jbe@magnetkern.de>
Date: Tue, 19 Jul 2022 23:53:40 +0200
Subject: [PATCH] fixup! docs: Improve AsRef / AsMut docs on blanket impls

Better conform to Rust API Documentation Conventions
---
 library/core/src/convert/mod.rs | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/library/core/src/convert/mod.rs b/library/core/src/convert/mod.rs
index e75e32855d1..bdd862f39c8 100644
--- a/library/core/src/convert/mod.rs
+++ b/library/core/src/convert/mod.rs
@@ -146,8 +146,9 @@ pub const fn identity<T>(x: T) -> T {
 /// let y: &i32 = &x;
 /// ```
 ///
-/// Types which implement [`Deref`][core::ops::Deref] should consider implementing `AsRef` as
-/// follows:
+/// Types which implement [`Deref`] should consider implementing `AsRef<T>` as follows:
+///
+/// [`Deref`]: core::ops::Deref
 ///
 /// ```
 /// # use core::ops::Deref;
@@ -172,12 +173,14 @@ pub const fn identity<T>(x: T) -> T {
 /// # Reflexivity
 ///
 /// Ideally, `AsRef` would be reflexive, that is there is an `impl<T: ?Sized> AsRef<T> for T`, with
-/// [`as_ref`][AsRef::as_ref] simply returning its argument unchanged.
+/// [`as_ref`] simply returning its argument unchanged.
 /// Such a blanket implementation is currently *not* provided due to technical restrictions of
 /// Rust's type system (it would be overlapping with another existing blanket implementation for
 /// `&T where T: AsRef<U>` which allows `AsRef` to auto-dereference, see "Generic Implementations"
 /// above).
 ///
+/// [`as_ref`]: AsRef::as_ref
+///
 /// A trivial implementation of `AsRef<T> for T` must be added explicitly for a particular type `T`
 /// where needed or desired. Note, however, that not all types from `std` contain such an
 /// implementation, and those cannot be added by external code due to orphan rules.
@@ -249,8 +252,10 @@ pub trait AsRef<T: ?Sized> {
 /// let y: &mut i32 = &mut x;
 /// ```
 ///
-/// Types which implement [`DerefMut`](core::ops::DerefMut) should consider to add an
-/// implementation of `AsMut` as follows:
+/// Types which implement [`DerefMut`] should consider to add an implementation of `AsMut<T>` as
+/// follows:
+///
+/// [`DerefMut`]: core::ops::DerefMut
 ///
 /// ```
 /// # use core::ops::{Deref, DerefMut};
@@ -279,12 +284,14 @@ pub trait AsRef<T: ?Sized> {
 /// # Reflexivity
 ///
 /// Ideally, `AsMut` would be reflexive, that is there is an `impl<T: ?Sized> AsMut<T> for T`, with
-/// [`as_mut`][AsMut::as_mut] simply returning its argument unchanged.
+/// [`as_mut`] simply returning its argument unchanged.
 /// Such a blanket implementation is currently *not* provided due to technical restrictions of
 /// Rust's type system (it would be overlapping with another existing blanket implementation for
 /// `&mut T where T: AsMut<U>` which allows `AsMut` to auto-dereference, see "Generic
 /// Implementations" above).
 ///
+/// [`as_mut`]: AsMut::as_mut
+///
 /// A trivial implementation of `AsMut<T> for T` must be added explicitly for a particular type `T`
 /// where needed or desired. Note, however, that not all types from `std` contain such an
 /// implementation, and those cannot be added by external code due to orphan rules.
@@ -298,7 +305,7 @@ pub trait AsRef<T: ?Sized> {
 ///
 /// In the following, the example functions `caesar` and `null_terminate` provide a generic
 /// interface which work with any type that can be converted by cheap mutable-to-mutable conversion
-/// into a byte slice or byte `Vec`, respectively.
+/// into a byte slice (`[u8]`) or byte vector (`Vec<u8>`), respectively.
 ///
 /// [dereference]: core::ops::DerefMut
 /// [target type]: core::ops::Deref::Target