Add more content to impl-trait.md

[tlyu]

Much of this comes from the edition-guide. Some information comes from the RFCs about the impl Trait feature. (rust-lang/rfcs#1522, rust-lang/rfcs#1951, and rust-lang/rfcs#2250)

Some finer points from the RFCs might need to be added, but maybe a new issue should be opened to enumerate and track those? I guess the biggest one would be checking that the syntax changes of rust-lang/rfcs#2250 are adequately documented in the reference. Lifetime defaults, especially for impl Trait in return position, should probably also be checked.

CC #276.

[ehuss]

Thanks for the PR! The placeholders have been hanging around for quite a long time.

This is written in a little more of a guide style, whereas we generally try to keep the reference closer to a specification style. However, having this is better than not, so I'm fine with merging it. However, I'll probably keep #276 open to further that work.

[ehuss]

Suggested change

> **Edition differences**: `impl Trait` is new in the 2018 edition.

The edition differences are only for things that change compilation based on the edition. The old style of the edition guide presenting all new features as part of the "edition" is being phased out.

[tlyu]

Thanks for the review! I had seen other parts of the reference using language like this. Is text like "impl Trait is not available in the 2015 edition" better? I think I saw some style guide saying to prefer that, but I can't seem to find it now.

[ehuss]

impl trait can be used on both 2015 and 2018. The only differences between the editions are listed here: https://doc.rust-lang.org/edition-guide/rust-2018/edition-changes.html

The reference conventions are listed here and there is a style guide here.

[tlyu]

Oh, I see. Apparently some new features were enabled in the 2015 edition after 2015, and only some (with syntax backward-incompatibilities?) were gated on edition=2018? I'm fine with deleting that note, then. (Though I also think the edition guide could use some better explanation about how new features found their way into the 2015 edition.)

[ehuss]

Yea. Usually new features work on all editions if possible. Only if it is backwards-incompatible in some way does it get gated on a new edition. FWIW, the edition guide is in the process of being rewritten.

[ehuss]

I can see how changing from generic parameter to impl trait would be a breaking change, but can you explain how the reverse is also a breaking change?

[tlyu]

I think this was based on text that I copied from the edition guide. For the reverse direction, I'm not especially familiar with using turbofish when there are multiple type parameters, e.g., what if we went from

fn foo<T: PartialOrd>(a: T, b: impl PartialOrd) {}
foo::<i32>(0, 1.0);

to

fn foo<T: PartialOrd, U: PartialOrd>(a: T, b: U) {}
foo::<i32>(0, 1.0);

Is it valid to omit the second type parameter? How does the compiler know which one is omitted? (I can't find any text in the reference about this case.) I'm sorry if this is a bad example.

[tlyu]

I experimented a bit in the playground, and it seems like in practice:

• If there are multiple type parameters, either all or none must be specified by turbofish
• If there is a mixture of type parameters and impl Trait in argument position, turbofish may not be used for any type arguments at all (edit: apparently this includes type parameters for the return type!)

Side note: are we avoiding using the term "turbofish" in the reference?

[ehuss]

I see. The second parameter can be omitted if it is defaulted, like <T, U=T>, but that can't be done with functions.

The reference normally doesn't discuss semver compatibility since that is a cargo concept (documented here). It's probably fine to leave this as-is, though.

There is one mention of turbofish, plus another in the glossary, but otherwise it usually doesn't come up.

[tlyu]

Some further experimentation suggests that both my proposed text and the edition guide are differently wrong:

• impl Trait in return position doesn't prevent the use of turbofish, contrary to the edition guide, which says that "In the case of impl Trait, if it is used anywhere in the function definition, then you can't use turbo-fish at all"
• impl Trait in any parameter type prevents the caller from providing any generic arguments at all, including return type and even const generics (No way to use fn with both const generics and impl Trait rust#85475)! This is contrary to my text, which says it only prevents turbofish for that parameter.

[tlyu]

While making the latest updates, I noticed that the text I copied from the edition guide uses "argument" in some places where it should use "parameter". The style guide doesn't specify explicitly (nor does either term seem to appear in the glossary), but most styles I've seen distinguish between "parameter" as an abstract input to a function, etc., and "argument" as the concrete input provided by a caller.

There's already some inconsistency out there in the Rust documentation, especially in phrasing like "impl Trait in argument position". Do we want to make any changes to make the usage more consistent on this page?

[ehuss]

Yea, it definitely should be consistent. You are correct that parameter is the variable declaration and argument is the value passed to a function. If I were writing it, I would phrase things like "impl Trait can only appear as a parameter or return type"

[tlyu]

Thanks! I've made the terminology more consistent, while keeping a few historical phrasings and adding a note about the use of wording like "impl Trait in argument position".

[ehuss]

Thanks!