]> git.lizzy.rs Git - rust.git/commit
Rollup merge of #99460 - JanBeh:PR_asref_asmut_docs, r=joshtriplett
authorMatthias Krüger <matthias.krueger@famsik.de>
Mon, 3 Oct 2022 18:58:54 +0000 (20:58 +0200)
committerGitHub <noreply@github.com>
Mon, 3 Oct 2022 18:58:54 +0000 (20:58 +0200)
commiteedb51210cf1c44be8e4a05ad41ca9709bbcdfc3
tree605b93ff7fa6c401dabd15bb71a44b8000d1a4bf
parent2110d2de5a894f3088e1d8f20404876e2ef4b65e
parente6b761b902fe80ba454368d078fb834554981109
Rollup merge of #99460 - JanBeh:PR_asref_asmut_docs, r=joshtriplett

docs: Improve AsRef / AsMut docs on blanket impls

There are several issues with the current state of `AsRef` and `AsMut` as [discussed here on IRLO](https://internals.rust-lang.org/t/semantics-of-asref/17016). See also #39397, #45742, #73390, #98905, and the FIXMEs [here](https://github.com/rust-lang/rust/blob/1.62.0/library/core/src/convert/mod.rs#L509-L515) and [here](https://github.com/rust-lang/rust/blob/1.62.0/library/core/src/convert/mod.rs#L530-L536). These issues are difficult to fix. This PR aims to update the documentation to better reflect the status-quo and to give advice on how `AsRef` and `AsMut` should be used.

In particular:

- 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
library/core/src/convert/mod.rs