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.
Not sure that "default-repr" is a standard term. Maybe "without an explicit repr attribute" or something?
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.
| /// 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.
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.
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.
Nixed the "use this whenever possible"; I agree it sounds a bit mystical here.
There was a problem hiding this comment.
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.
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
KnownLayoutonSizedtypes, so we shouldn't imply that that's the only time when it's needed. - We may make
KnownLayoutsmarter 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.
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
KnownLayoutonSizedtypes, so we shouldn't imply that that's the only time when it's needed.- We may make
KnownLayoutsmarter 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_ofandmem::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.