-
Notifications
You must be signed in to change notification settings - Fork 98
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document KnownLayout
#988
Document KnownLayout
#988
Conversation
src/lib.rs
Outdated
/// # Limitations | ||
/// | ||
/// This derive cannot currently be applied to unsized structs with the | ||
/// default-`repr`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure that "default-repr
" is a standard term. Maybe "without an explicit repr
attribute" or something?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
src/lib.rs
Outdated
/// internals of this crate. | ||
/// Implements [`KnownLayout`]. | ||
/// | ||
/// This derive analyzes various qualities of a type's layout that are needed |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/// This derive analyzes various qualities of a type's layout that are needed | |
/// This derive analyzes various properties of a type's layout that are needed |
Alternatively, "aspects"?
Same below in the other doc comment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
src/lib.rs
Outdated
/// Implements [`KnownLayout`]. | ||
/// | ||
/// This derive analyzes various qualities of a type's layout that are needed | ||
/// for some of zerocopy's APIs. It should be used whenver possible, and can be |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we be suggesting "use this whenever possible", or just leave it up to users to discover (via bounds) when they need to derive it? It seems redundant given that the bounds will guide them to when they need to derive KnownLayout
. It adds extra prose that, to me, sounds a tad mystical.
Same elsewhere in this PR.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nixed the "use this whenever possible"; I agree it sounds a bit mystical here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That said, I'd like to keep it in the crate-level overview.
Documents the derive, and aligns the trait documentation with that of other traits.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might be worth explicitly calling out that this supports unsized slice DST types, and providing examples in the documentation. We'll have to be a bit careful because:
- We also require
KnownLayout
onSized
types, so we shouldn't imply that that's the only time when it's needed. - We may make
KnownLayout
smarter in the future and use it encode other information that lets us do things besides slice DST stuff.
That said, I could imagine someone thinking, "why do you need this if you have mem::size_of
and mem::align_of
?", and it could be good to respond to that thought.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It might be worth explicitly calling out that this supports unsized slice DST types, and providing examples in the documentation. We'll have to be a bit careful because:
- We also require
KnownLayout
onSized
types, so we shouldn't imply that that's the only time when it's needed.- We may make
KnownLayout
smarter in the future and use it encode other information that lets us do things besides slice DST stuff.That said, I could imagine someone thinking, "why do you need this if you have
mem::size_of
andmem::align_of
?", and it could be good to respond to that thought.
Discussed offline; will follow up in #993
Documents the derive, and aligns the trait documentation with that of other traits.