Refactor unsizing coercion documentation #1731
Conversation
rustbot
added
the
S-waiting-on-review
WaffleLapkin
force-pushed
the
unsize_coercion_rewrite
branch
3 times, most recently
from
6f8650a to
08bec64
Compare
This comment has been minimized.
This comment has been minimized.
|
@rust-lang/types would you be able to review this? |
|
To add a bit more color, it'd be good to get a double check that the content is factually accurate before spec team takes it on for editorial review. |
src/type-coercions.md
Outdated
| <!-- FIXME: are there more requirements for `CoerceUnsized`? --> | ||
|
|
||
| r[coerce.unsize.coerce-unsized-impls] | ||
| Types which currently implement `CoerceUnsized<_>` (assuming `T: Unsize<U>`, `'a: 'b`, `A: CoerceUnsized<B>`, `Al: Allocator`): |
There was a problem hiding this comment.
Generally I would prefer to not duplicate the list of impls from the standard library here. I assume the user can click the link to CoerceUnsized to see which impls it has?
There was a problem hiding this comment.
So, mh. Yes, users can find them in the std docs (that's where I got the impls from!).
However, if we want the reference to be prescriptive, I think we should include this. While this is library code, it controls how a language feature behaves.
But I don't have a strong opinion here, if you think that this is not useful I can remove the list.
WaffleLapkin
force-pushed
the
unsize_coercion_rewrite
branch
from
08bec64 to
9271fdd
Compare
|
@WaffleLapkin To move this along, would it be possible to split this PR up a little so it doesn't get hung up? In particular, I think it would move things faster if we remove the name change (unsized -> unsizing) to avoid getting stuck on bikeshedding (that doesn't mean we can't make that change separately, it just adds friction). And remove the list of You can either just make this PR smaller, or open a new smaller PR, whichever is more convenient. Assigning TC since he asked. |
WaffleLapkin
force-pushed
the
unsize_coercion_rewrite
branch
2 times, most recently
from
b68840f to
56ee0bb
Compare
|
I can review this over the weekend |
WaffleLapkin
force-pushed
the
unsize_coercion_rewrite
branch
from
56ee0bb to
2a242c5
Compare
The old one was quite confusing and also incorrect in a few places.
WaffleLapkin
force-pushed
the
unsize_coercion_rewrite
branch
from
2a242c5 to
7780344
Compare
|
@ehuss I forgot to comment, but I removed the impls and split off the rename. |
| When performing unsized coercion, the pointer metadata type changes. For example, when unsized `&u32` to `&dyn Debug` metadate type changes from `()` to `DynMetadata<dyn Debug>` (note that exact metadata types are not yet stable). This can also lead to a change in the pointer size -- `&u32` is half the size of `&dyn Debug`. | ||
|
|
||
| r[coerce.unsize.traits] | ||
| Three traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are used to assist in this process and expose it for library use. |
There was a problem hiding this comment.
It may be worth clarifying these traits are unstable.
There was a problem hiding this comment.
There's a note about this down on line 273.
This is actually an interesting case. Generally in the Reference we don't document the unstable, just the exposed stable behaviors. But here, it's probably indeed easiest to describe those stable behaviors in terms of the unstable traits, and we'd already made this exception.
| Additionally, a type `Foo<T>` can implement `CoerceUnsized<Foo<U>>` when `T` | ||
| implements `Unsize<U>` or `CoerceUnsized<Foo<U>>`. This allows it to provide an | ||
| unsized coercion to `Foo<U>`. | ||
| <!-- FIXME: are there more requirements for `CoerceUnsized`? --> |
There was a problem hiding this comment.
So, I think another constraint here is that only one field can be coerced.
The old one was quite confusing and also incorrect in a few places. Follow-up to #1622.