Document fully-qualified syntax in as' keyword doc
#142670
Conversation
|
r? @ibraheemdev rustbot has assigned @ibraheemdev. Use |
rustbot
added
S-waiting-on-review
library/std/src/keyword_docs.rs
Outdated
| @@ -24,6 +24,13 @@ | |||
| /// (`u8`, `bool`, `str`, pointers, ...) whereas `From` and `Into` also works with types like | |||
| /// `String` or `Vec`. | |||
| /// | |||
| /// You'll also find with `From` and `Into`, and indeed all traits, that `as` is used for the | |||
| /// _fully qualified syntax_, a means of clarifying ambiguous method calls. If you have a type which | |||
There was a problem hiding this comment.
I would use fully qualified path here over syntax because that's more precise and what The Reference and rustc calls it.
There was a problem hiding this comment.
Ah ok I couldn't find it in the reference. It's called syntax in the rust book, but I certainly like path better.
library/std/src/keyword_docs.rs
Outdated
| @@ -24,6 +24,13 @@ | |||
| /// (`u8`, `bool`, `str`, pointers, ...) whereas `From` and `Into` also works with types like | |||
| /// `String` or `Vec`. | |||
| /// | |||
| /// You'll also find with `From` and `Into`, and indeed all traits, that `as` is used for the | |||
| /// _fully qualified syntax_, a means of clarifying ambiguous method calls. If you have a type which | |||
There was a problem hiding this comment.
This is not just for method calls, it's for all three kinds of associated item: Function, constant and type.
fpdotmonkey
force-pushed
the
doc/as-fully-qualified-syntax
branch
from
7cfd0dd to
a2d247b
Compare
| /// _fully qualified path_, a means of clarifying ambiguous method calls, constants, and types. | ||
| /// If you have a type which implements two traits with identical method names (e.g. | ||
| /// `Into<u32>::into` and `Into<u64>::into`), you can clarify which method you'll use with | ||
| /// `<MyThing as Into<u32>>::into(my_thing)`. This is quite verbose, but fortunately, Rust's type |
There was a problem hiding this comment.
Are there any other std traits where this is commonly needed? A small downside with this example is that this is something that should just be written u32::from(my_thing) 🙂
There was a problem hiding this comment.
It could be a thing with Debug vs Display::fmt. That said, <Self as fmt::Debug>::fmt(self, f) is semantically identical, longer, and weirder than fmt::Debug::fmt(self, f). io::Write::write_fmt and fmt::Write::write_fmt have the same problem.
Into<T> is nice since it's reasonably likely that users will encounter a message from rustc that they should use the fully-qualified path as in these docs (though by all rights, it should suggest that you should use T::from(self)).
An other option would be to make a contrived exampled like is done in the Rust book. E.g.,
struct Person;
trait MetalHead {
fn head_bang();
}
trait SalaryWorker {
fn head_bang();
}
impl MetalHead for Person { ... }
impl SalaryWorker for Person { ... }
// 9 to 5
<Person as SalaryWorker>::head_bang();
// 5 to 9
<Person as MetalHead>::head_bang();But of course coming up with a more useful example is hard since associated items don't usually overlap and there's usually sufficient type information to remove the ambiguity this doc is trying to highlight. The optimal example would be either a pair of trait methods that return a generic type like Into::<T>::into, or a pair of static trait methods. Short of what's here already, I can't find anything like that.
No description provided.