update coerce docs and unify relevant tests

[lcnr]

Merges test/ui/coerce with test/ui/coercion.
Updates the documentation of librustc_typeck/check/coercion.rs.
Adds 2 new coercion tests.

[rust-highfive]

r? @estebank

(rust_highfive has picked a reviewer for you, use r? to override)

[lcnr]

@estebank I reverted the change fromCoerce to CoerceCtxt as it doesn't fit too well with the rest of this PR.

[bors]

☔ The latest upstream changes (presumably #73486) made this pull request unmergeable. Please resolve the merge conflicts.

[estebank]

Only one nitpick, r=me.

[estebank]

Should we add an explanation for the foo::<&i32>(&7, &mut 7) case?

[lcnr]

Hmm isn't foo::<&i32>(&7, &mut 7) fairly trivial as there are no type variables at play here?

Or do you want me to add a more detailed explanation for foo(&7, &mut 7)? My current explanation is
fairly short.

foo(&7i32, &mut 7i32);
// This compiles, as we first infer `T` to be `&i32`,
// and then coerce `&mut 7i32` to `&7i32`.

[estebank]

I'm referring at keeping part of the following info around, unless it is no longer valid:

rust/src/librustc_typeck/check/coercion.rs

Lines 34 to 51 in 72417d8

	//! ## Subtler note
	//!
	//! However, right now, if the user manually specifies the
	//! values for the type variables, as so:
	//!
	//! foo::<&int>(@1, @2)
	//!
	//! then we *will* auto-borrow, because we can't distinguish this from a
	//! function that declared `&int`. This is inconsistent but it's easiest
	//! at the moment. The right thing to do, I think, is to consider the
	//! *unsubstituted* type when deciding whether to auto-borrow, but the
	//! *substituted* type when considering the bounds and so forth. But most
	//! of our methods don't give access to the unsubstituted type, and
	//! rightly so because they'd be error-prone. So maybe the thing to do is
	//! to actually determine the kind of coercions that should occur
	//! separately and pass them in. Or maybe it's ok as is. Anyway, it's
	//! sort of a minor point so I've opted to leave it for later -- after all,
	//! we may want to adjust precisely when coercions occur.

[lcnr]

I think this isn't relevant anymore as we now auto-borrow both foo::<&i32>(&7, &mut 7) and foo(&7, &mut 7).

Afaict there was a time where we did not compile foo(&7, &mut 7) to prevent the inconsistency we have rn (where foo(&7, &mut 7) compiles and foo(&mut 7, &7) does not).

So the fact that coercion doesn't distinguish foo<&i32> from fn foo(_: &i32, _: &i32) shouldn't matter anymore.

[estebank]

@bors r+

[bors]

📌 Commit 06a237f has been approved by estebank