Document fully-qualified syntax in `as`' keyword doc #142670

fpdotmonkey · 2025-06-18T12:11:24Z

No description provided.

rustbot · 2025-06-18T12:11:28Z

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

library/std/src/keyword_docs.rs

tgross35 · 2025-06-19T02:26:50Z

library/std/src/keyword_docs.rs

+/// _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


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) 🙂

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.

I've changed it so there's a footnote saying that it'd be better to use T::from(my_thing) and that the example is imperfect.

ibraheemdev · 2025-06-25T18:45:19Z

library/std/src/keyword_docs.rs

+/// _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.


Just a small nit.

Suggested change

/// _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.

/// _fully qualified path_, a means of clarifying ambiguous associated items. For example,

/// if you have a type which implements two traits with identical method names (e.g.

Happy to make this change, but isn't this a bit less useful? As it was, it tells you exactly which syntactic objects this syntax can be used with, whereas the change demands that you know about the associated item abstraction. Realistically, if I'm someone who's reading the keyword docs, I'm probably a rust beginner and probably not familiar with this abstraction.

Perhaps "a means of clarifying ambiguous associated items, i.e. methods, constants, and types. For example," would be a good compromise?

(I'm not the primary reviewer) if you end up listing the three kinds of associated item, please substitute method with function or with function (includes methods). Methods are only a subset of associated functions.

ibraheemdev · 2025-06-25T18:46:31Z

r=me after the nit.

ibraheemdev · 2025-06-27T14:28:37Z

@bors r+ rollup

bors · 2025-06-27T14:28:40Z

📌 Commit 15f73ab has been approved by ibraheemdev

It is now in the queue for this repository.

fmease · 2025-06-27T15:31:35Z

library/std/src/keyword_docs.rs

@@ -24,6 +24,20 @@
 /// (`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


(Revisiting this after seeing #143098)

This paragraph is placed in the middle of the as casts explainer. E.g., below it continues to talk about as _ which is confusing and disrupts the flow. Please move it to the bottom.

Furthermore, I think we should quickly mention associated items in the synopsis / introductory paragraph to give this more structure.

fmease · 2025-06-27T15:33:38Z

library/std/src/keyword_docs.rs

@@ -24,6 +24,20 @@
 /// (`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 path_, a means of clarifying ambiguous associated items, i.e. functions,


Suggested change

/// _fully qualified path_, a means of clarifying ambiguous associated items, i.e. functions,

/// _fully qualified path_, a means of disambiguating associated items, i.e. functions,

fmease · 2025-06-27T15:34:24Z

library/std/src/keyword_docs.rs

+/// you'll use with `<MyThing as Into<u32>>::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
+/// static methods.  It's more common to use in macros where it can provide necessary hygeine.


Suggested change

/// static methods. It's more common to use in macros where it can provide necessary hygeine.

/// static methods. It's more common to use in macros where it can provide necessary hygiene.

fmease · 2025-06-27T15:34:53Z

@bors r-

rustbot assigned ibraheemdev Jun 18, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 18, 2025

fmease reviewed Jun 18, 2025

View reviewed changes

library/std/src/keyword_docs.rs Outdated Show resolved Hide resolved

library/std/src/keyword_docs.rs Outdated Show resolved Hide resolved

fpdotmonkey force-pushed the doc/as-fully-qualified-syntax branch from 7cfd0dd to a2d247b Compare June 18, 2025 13:32

tgross35 reviewed Jun 19, 2025

View reviewed changes

ibraheemdev reviewed Jun 25, 2025

View reviewed changes

ibraheemdev added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 25, 2025

fpdotmonkey force-pushed the doc/as-fully-qualified-syntax branch 2 times, most recently from 054ee36 to 15f73ab Compare June 27, 2025 10:52

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 27, 2025

fmease requested changes Jun 27, 2025

View reviewed changes

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Jun 27, 2025

fmease mentioned this pull request Jun 27, 2025

fix(keyword_docs.rs): use of as keyword to disambiguate paths #143098

Open

Document fully-qualified syntax in as' keyword doc

c7fd35f

fpdotmonkey force-pushed the doc/as-fully-qualified-syntax branch from 15f73ab to c7fd35f Compare June 30, 2025 11:37

		/// _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.

	/// _fully qualified path_, a means of clarifying ambiguous associated items, i.e. functions,
	/// _fully qualified path_, a means of disambiguating associated items, i.e. functions,

	/// static methods. It's more common to use in macros where it can provide necessary hygeine.
	/// static methods. It's more common to use in macros where it can provide necessary hygiene.

Document fully-qualified syntax in as' keyword doc #142670

Are you sure you want to change the base?

Document fully-qualified syntax in as' keyword doc #142670

Conversation

fpdotmonkey commented Jun 18, 2025

Uh oh!

rustbot commented Jun 18, 2025

Uh oh!

Uh oh!

Uh oh!

tgross35 Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

fpdotmonkey Jun 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fpdotmonkey Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

ibraheemdev Jun 25, 2025

Choose a reason for hiding this comment

Uh oh!

fpdotmonkey Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

fmease Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibraheemdev commented Jun 25, 2025

Uh oh!

ibraheemdev commented Jun 27, 2025

Uh oh!

bors commented Jun 27, 2025

Uh oh!

fmease Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

fmease Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

fmease Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

fmease commented Jun 27, 2025

Uh oh!

Uh oh!

Document fully-qualified syntax in `as`' keyword doc #142670

Document fully-qualified syntax in `as`' keyword doc #142670

fpdotmonkey Jun 19, 2025 •

edited

Loading

fmease Jun 27, 2025 •

edited

Loading

fmease Jun 27, 2025 •

edited

Loading