Improve doc for 'as _'

[poliorcetics]

Fix #78042.

@rustbot modify labels: A-coercions T-doc

[rust-highfive]

r? @Mark-Simulacrum

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

[Mark-Simulacrum]

cc @jonas-schievink

I am not sure that this is a good thing to document. I think it can be confusing to see foo as _, but it feels like that's sort of a reason to not do that rather than a reason to document it. Certainly it makes inference breakage even more likely than alternative patterns.

Perhaps we could add a note that "usually, such code should be written with an explicit type"?

[poliorcetics]

I added a note about clarity and stability, is it better ?

[cher-nov]

I would also request for some clarification of similarities and differences between as / From:: and as _ / .into(), as was noted in the original issue.

[poliorcetics]

From and Into are not as easily separated, here is a counter example:

fn main() {
    let a = 1_u8;
    let b = a.into(); // The only in the snippet error occurs here.

    let c = From::from(a);
    take(c);
}

fn take(_: u16) {}

[cher-nov]

From and Into are not as easily separated, here is a counter example:

Well, what I actually meant is to clarify a bit why do we need as T and as _ if we also have From::<T> and .into().
I'm just learning Rust now, and this question wasn't intuitive for me at all. So I would appreciate some notes on this to make newbies experience a bit easier. :)

[poliorcetics]

Oh sorry, I didn't understand what you wanted. I'm not sure how to explain it though.

Quick draft below, is it enough ?

`as` can be seen as the primitive for `From` and `Into`: `as` only works 
with primitives (`u8`, `bool`, `str`, pointers, ...) whereas `From` and `Into` 
also works with types like `String` or `Vec`.

I'm not sure if the part about as only working with primitives is completely true.

[cher-nov]

Oh sorry, I didn't understand what you wanted. I'm not sure how to explain it though.

Oh, nevermind. I'm not a native English speaker, so it's pretty possible that I just can't describe what I want properly.

Quick draft below, is it enough ?

LGTM ;)

[poliorcetics]

I removed the example and added a point about *const/mut _ specifically, putting a link towards the cast methods for both.

[Mark-Simulacrum]

It looks like there's a merge conflict; but the current text looks okay to me. I am still not 100% on this being a good thing to add, but it does seem like some folks at least are in favor so I'm not going to block it, and I could see it being useful.

r=me with conflicts fixed

[Dylan-DPC-zz]

@poliorcetics if you can resolve the conflicts, we can merge this

[poliorcetics]

Sorry I completely forgot about this !

Edit: I had to merge my changes to the docs with some other so the text changed a little and probably deserves another read-over

[poliorcetics]

@rustbot modify labels: -S-waiting-on-author +S-waiting-on-review

[Mark-Simulacrum]

Please squash commits; we should not have a "Fix rebase" commit in history if it can be avoided.

[poliorcetics]

@rustbot modify labels: -S-waiting-on-author +S-waiting-on-review

[Mark-Simulacrum]

@bors r+ rollup

[bors]

📌 Commit e31e627 has been approved by Mark-Simulacrum