diff --git a/library/std/src/keyword_docs.rs b/library/std/src/keyword_docs.rs index 1c55824ab9061..873f1f720f4bb 100644 --- a/library/std/src/keyword_docs.rs +++ b/library/std/src/keyword_docs.rs @@ -3,8 +3,8 @@ /// Cast between types, or rename an import. /// /// `as` is most commonly used to turn primitive types into other primitive types, but it has other -/// uses that include turning pointers into addresses, addresses into pointers, and pointers into -/// other pointers. +/// uses that include turning pointers into addresses, addresses into pointers, pointers into +/// other pointers, and qualifying paths for associated items. /// /// ```rust /// let thing1: u8 = 89.0 as u8; @@ -37,9 +37,26 @@ /// use std::{mem as memory, net as network}; /// // Now you can use the names `memory` and `network` to refer to `std::mem` and `std::net`. /// ``` -/// For more information on what `as` is capable of, see the [Reference]. -/// -/// [Reference]: ../reference/expressions/operator-expr.html#type-cast-expressions +/// You'll also find with `From` and `Into`, and indeed all traits, that `as` is used for the +/// _fully qualified path_, a means of disambiguating associated items, i.e. functions, +/// constants, and types. For example, if you have a type which implements two traits with identical +/// method names (e.g. `Into::::into` and `Into::::into`), you can clarify which method +/// you'll use with `>::into(my_thing)`[^as-use-from]. This is quite verbose, +/// but fortunately, Rust's type inference usually saves you from needing this, although it is +/// occasionally necessary, especially with methods that return a generic type like `Into::into` or +/// methods that don't take `self`. It's more common to use in macros where it can provide necessary +/// hygiene. +/// +/// [^as-use-from]: You should probably never use this syntax with `Into` and instead write +/// `T::from(my_thing)`. It just happens that there aren't any great examples for this syntax in +/// the standard library. Also, at time of writing, the compiler tends to suggest fully-qualified +/// paths to fix ambiguous `Into::into` calls, so the example should hopefully be familiar. +/// +/// For more information on what `as` is capable of, see the Reference on [type cast expressions] +/// and [qualified paths]. +/// +/// [type cast expressions]: ../reference/expressions/operator-expr.html#type-cast-expressions +/// [qualified paths]: ../reference/paths.html#qualified-paths /// [`crate`]: keyword.crate.html /// [`use`]: keyword.use.html /// [const-cast]: pointer::cast