docs: Improve AsRef / AsMut docs on blanket impls

- Explicitly mention that `AsRef` and `AsMut` do not auto-dereference
  generally for all dereferencable types (but only if inner type is a
  shared and/or mutable reference)
- Give advice to not use `AsRef` or `AsMut` for the sole purpose of
  dereferencing
- Suggest providing a transitive `AsRef` or `AsMut` implementation for
  types which implement `Deref`
- Add new section "Reflexivity" in documentation comments for `AsRef`
  and `AsMut`
- Provide better example for `AsMut`
- Added heading "Relation to `Borrow`" in `AsRef`'s docs to improve
  structure

Issue #45742 and a corresponding FIXME in the libcore suggest that
`AsRef` and `AsMut` should provide a blanket implementation over
`Deref`. As that is difficult to realize at the moment, this commit
updates the documentation to better describe the status-quo and to give
advice on how to use `AsRef` and `AsMut`.

0 files changed, 0 insertions, 0 deletions